9.1 KiB
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.