Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,149 @@
# Architektur-Vorschriften (Querschnitt)
Diese 20 Vorschriften gelten **modulübergreifend für die gesamte Plattform**. Sie sind Bauprinzipien, nicht Funktionen, daher in einem eigenen Kapitel und nicht pro Modul wiederholt. Pro Modul wird in der jeweiligen Modul-Section verwiesen, welche Vorschriften besonders relevant sind.
## A.1 Klartext-Diagnostik in jedem Feature
A.1.1 Jeder erkennbare Fehler-Zustand hat einen **fest formulierten Klartext-Text** und (wo sinnvoll) einen **Lösungs-Knopf**. Nicht „401 Unauthorized" sondern „Die Verbindung zur Buchhaltungs-Software ist abgelaufen, bitte einmal neu anmelden. [Anmelden]".
A.1.2 **Keine KI-on-the-fly-Übersetzung von Fehlertexten** in Phase 1. Texte sind redaktionell vorgefertigt, durchsuchbar, mehrsprach-fähig (über das i18n-Modul M30).
A.1.3 Kein Feature wird freigegeben, bevor die Klartext-Texte definiert und im Pflichtenheft des jeweiligen Moduls aufgeführt sind.
## A.2 Adapter-Schicht für jede Integration
A.2.1 Externe Systeme (KWP, Gmail, AirCall, Stripe, PandaDoc, Calendar, ...) werden **nur über die Apps-Engine** (Modul 33a) angebunden, nie direkt aus einem Modul heraus.
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.
A.2.3 Verbindungs-Status, Sync-Jobs und Klartext-Diagnostik sind **über alle Apps einheitlich**: gleiche Anzeige, gleiche Bedien-Logik.
## A.3 Branchen-Templates deklarativ, nicht hartkodiert
A.3.1 Standard-Pipelines (Sales, Auftrag), Standard-Rollen, Standard-Automatisierungen pro Branche werden in **Konfigurations-Dateien** abgelegt, nicht als Code.
A.3.2 Onboarding-Wizard liest aus diesen Konfigurationen. Eine neue Branche bedeutet: Konfigurations-Datei dazu, keine Code-Änderung.
A.3.3 Phase 1: SHK pre-selected. Andere Branchen sichtbar als „Coming soon".
## A.4 Mehrsprachigkeit von Anfang an sauber vorbereitet
A.4.1 **Kein einziger UI-Text** wird hartkodiert. Alle Texte kommen aus Sprach-Dateien (Locale-Files).
A.4.2 Phase 1: nur Deutsch befüllt. Phase 2: DeepL-Pipeline für DE → EN/TR/PL.
A.4.3 Sprach-Wechsel pro Nutzer (nicht pro Mandant), ein deutscher Mitarbeiter und ein türkischer Mitarbeiter im selben Mandanten sehen unterschiedliche Sprachen.
## A.5 Berechtigungs-Logik als Standard, nicht als Sonderfall
A.5.1 Jede Liste, jede Suche, jede Detail-Ansicht filtert **automatisch** nach den Berechtigungen des angemeldeten Nutzers. Ein Nutzer ohne Lese-Recht auf Modul X sieht es nicht im Menü, kann es nicht aufrufen, taucht nicht in der Suche auf.
A.5.2 **Owner-Check** für „eigene Daten" (z. B. Vertriebler darf nur seine eigenen Verkaufsfälle sehen): wird zentral implementiert, nicht pro Modul nachgebaut.
A.5.3 Es gibt **keine versteckten URL-Tricks**, mit denen man Berechtigungen umgehen kann.
## A.6 Audit-Log als Default
A.6.1 **Jede schreibende Aktion** (Anlegen, Ändern, Löschen, Status-Wechsel) wird mit Wer, Wann, Was, Vor-/Nach-Wert ins Audit-Log geschrieben (Modul 21).
A.6.2 Das gilt auch für Aktionen, die durch Automatisierungen oder durch externe Sync-Vorgänge ausgelöst werden, der Auslöser wird mit-protokolliert.
## A.7 Feature-Flags als Standard-Einführungs-Hülle
A.7.1 Neue Features werden hinter einem Feature-Flag eingeführt (Modul 32), erst für interne Tests, dann für ausgewählte Mandanten, dann breit ausgerollt.
A.7.2 Bricht etwas, schaltet der Plattform-Admin den Flag aus, ohne Deploy.
## A.8 Idempotenz pro Automatisierungs-Aktion
A.8.1 Jeder Schritt einer Automatisierung hat einen **Idempotenz-Schlüssel**: wird derselbe Schritt zweimal ausgeführt (z. B. nach einem Retry), wird die Aktion nicht doppelt durchgeführt.
A.8.2 Konkret: keine doppelten Mails, keine doppelten Datensätze, keine doppelten KWP-Push-Operationen.
## A.9 Anti-Liste und Change-Request-Mechanismus
A.9.1 Was nicht im Pflichtenheft steht, **ist nicht beauftragt**. Punkt.
A.9.2 Jede Erweiterung nach Sign-off geht über die Change-Request-Liste, mit Datum, Zustimmungs-Vermerk und Auswirkung auf Zeitplan/Aufwand.
A.9.3 **Kein stillschweigendes Mitnehmen** in Phase 1 („Wir hatten doch besprochen ...").
## A.10 Vorschau und Rückgängig für KI-Aktionen
A.10.1 Eine KI-erzeugte Automatisierung wird **nie direkt scharfgeschaltet**: immer Vorschau mit konkreter Auswirkung („würde 1.400 Personen betreffen, hier die ersten 5: ...") und User-Bestätigung.
A.10.2 **24-Stunden-Rückgängig-Fenster** für die Wirkungen einer Automatisierung, innerhalb 24h können angelegte Datensätze, Status-Änderungen, Tag-Änderungen rückgängig gemacht werden. Versendete Mails sind nicht zurückziehbar, aber die Empfänger-Liste ist sichtbar.
## A.11 Schema-Drift-Sentinel für ERP-Anbindungen
A.11.1 Tägliche Prüfung gegen die KWP-Datenbank: existieren erwartete Tabellen, Spalten, Datentypen noch?
A.11.2 Bei Abweichung: Push-Alarm an Plattform-Admin (uns), bevor Geerkens den Bruch live merkt.
## A.12 EU-Stack komplett
A.12.1 **Hosting:** Scaleway (Frankreich, Niederlande).
A.12.2 **Datenbank:** in EU.
A.12.3 **KI-Anbieter:** ausschließlich EU. Mistral (primär), Scaleway-Hosted-Modelle (sekundär), AlephAlpha (tertiär). **Kein Anthropic, kein OpenAI.**
A.12.4 Trade-off bewusst: Modell-Qualität ist nicht GPT-5-Niveau, ist aber für unsere Anwendungsfälle ausreichend. Marketing-Argument: „100 % EU, 100 % DSGVO".
## A.13 Multi-Provider-Fallback für KI
A.13.1 Wenn der primäre KI-Anbieter ausfällt (Mistral 30 Min nicht erreichbar), wird automatisch auf den zweiten umgeschaltet.
A.13.2 Wenn alle KI-Anbieter ausfallen: KI-getriebene UI-Elemente zeigen Klartext-Hinweis und Fallback-Modus („Bitte nutze den visuellen Editor stattdessen").
A.13.3 Deterministische KI-Antworten (gleiche Frage → gleiche Antwort) werden gecacht.
## A.14 Promptfoo-Eval-Suite mit Injection-Vektoren
A.14.1 Jeder neue KI-Prompt-Flow wird mit einer Test-Suite (Promptfoo) gegen Standard-Injection-Vektoren geprüft.
A.14.2 Continuous Integration, nicht einmaliger Build-Test.
A.14.3 Bösartige Eingaben (Form-Submission, Email-Inhalt) werden niemals direkt als Anweisung an die KI weitergereicht.
## A.15 Optimistic Locking + Last-Write-Wins-mit-Sichtbarkeit für ERP-Sync-Konflikte
A.15.1 Wenn jemand in HiveGrid eine Auftrag bearbeitet, während Sandra ihn parallel in KWP ändert: System erkennt den Versions-Konflikt beim Speichern und zeigt einen **Diff-View** zur Auflösung.
A.15.2 Wenn das nicht erkannt wurde (z. B. weil die Bearbeitung in KWP nicht gemeldet ist): **Last-Write gewinnt**, aber der Überschreiber bekommt eine Klartext-Notification mit Restore-Knopf.
## A.16 Rate-Limit + Anomalie-Erkennung für Automatisierungs-Trigger
A.16.1 **Hartes Limit:** pro Mandant max. 1.000 Trigger pro Stunde (konfigurierbar). Rest wird verworfen mit Notification.
A.16.2 **Anomalie-Erkennung:** wenn Trigger-Rate plötzlich 10× über dem Normalwert liegt, wird die Automatisierung pausiert mit Klartext-Hinweis: *„Diese Automatisierung wurde 2.000-mal in 5 Minuten ausgelöst, typisch sind 5-10 pro Tag. Wir haben sie pausiert. Bitte prüfen."*
## A.17 Schleifen-Schutz mit Klartext-Stopp und Pre-Save-Validierung
A.17.1 **Hartes Limit:** max. 5 Auto-Trigger pro Datensatz pro 60 Sekunden. Danach Abbruch.
A.17.2 Bei Abbruch: visuelle Darstellung der Trigger-Kette und Klartext-Hinweis: *„Automatisierung A löst B aus, B löst A aus, Schleife erkannt, beide pausiert."*
A.17.3 **Pre-Save-Validierung beim Erstellen:** System prüft Abhängigkeits-Graph beim Speichern und warnt vor potenziellen Schleifen.
## A.18 Heartbeat und Auto-Wiederherstellung für ERP-Sync-Programme
A.18.1 Das Sync-Programm beim Kunden vor Ort (heute: kwpsync.exe) sendet alle 5 Minuten ein Lebenszeichen an HiveGrid.
A.18.2 Bleibt das Lebenszeichen 15 Minuten aus: Alarm an Plattform-Admin und Sandra (Geerkens).
A.18.3 Sync-Programm läuft als Windows-Dienst (mit NSSM-Wrapper), automatischer Neustart bei Absturz, automatischer Start nach Reboot.
## A.19 Persistente Warteschlange mit Zeitstempeln und Rate-begrenztes Wiedereinspielen
A.19.1 Wenn HiveGrid 6 Stunden ausfällt, sammelt das Sync-Programm vor Ort alle Operationen in einer lokalen Warteschlange (SQLite, unbegrenzte Größe).
A.19.2 Beim Wiederhochfahren: chronologisches Wiedereinspielen, max. 100 Operationen pro Minute (Rate-Limit), sichtbarer Fortschritts-Indikator.
A.19.3 Bei Konflikten zwischen Warteschlange und HiveGrid-Stand: Klartext-Konflikt-Anzeige, Nutzer entscheidet welcher Stand gilt.
## A.20 Aktions-Grenze für KI: keine schreibenden Aktionen aus externen Quellen ohne Bestätigung
A.20.1 Die KI darf aus RAG-Kontext (Suche in eigenen Daten) oder aus externen Daten (eingehende Email, Form-Submission) **niemals direkt** schreibende Aktionen (Email senden, Datensatz anlegen, Stage ändern) ableiten.
A.20.2 Eine solche Aktion muss immer durch eine **separate User-Bestätigung** gehen, auch wenn die KI sicher ist.
A.20.3 Phase-1-Regel zur Vertrauensbildung. Wird in Phase 2 (autonome Agents) eventuell gelockert.