Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/intel/constraints.md
T
2026-07-08 16:15:37 +02:00

11 KiB

HiveGrid Intel — Constraints (SPEC / INTEGRATION-CONTRACTS)

Extracted technical contracts: API-contracts, schema constraints, NFRs, protocols. extracted: 2026-06-07


C-01 — Postgres-RLS: Pflicht-Policies auf allen tenant-scoped Tabellen

type: schema source: docs/ARCHITECTURE-DECISIONS.md (AD-1)

  • RLS-Policy USING/WITH CHECK als Forward-Migration mit Inverse-SQL-Kommentar auf jeder tenant-scoped Tabelle
  • App-DB-Rolle darf kein BYPASSRLS haben
  • Request-Middleware MUSS SET LOCAL app.tenant_id setzen vor dem ersten Query
  • Worker/Job muss Tenant-Context-Wrapper verwenden
  • Ausnahmen (kein RLS): users, subscription_*, feature_flags, Branchen-Templates
  • Cache-Präfix: tenant:{id}: (Redis); S3-Pfad: tenants/{id}/ (Scaleway)

C-02 — Keine polymorphe Entity/Row/RowValue-Engine

type: schema source: docs/ARCHITECTURE-DECISIONS.md (AD-2)

  • Das Boilerplate-CRM (apps/web/app/modules/crm, Entity+Row+RowValue) wird entfernt
  • Alle Fachentitäten (CRM, Deals, Aufträge, Tasks) als dedizierte Prisma-Tabellen
  • Custom-Felder ausschließlich über CustomFieldDefinition + CustomFieldValue (JSONB-Wert)
  • Polymorphes RowValue darf nicht für neue Entitäten verwendet werden

C-03 — AdminUser/AdminSession: vollständig getrennt von User/Session

type: schema source: docs/ARCHITECTURE-DECISIONS.md (AD-3), docs/INTEGRATION-CONTRACTS.md

  • AdminUser: eigene Tabelle mit passwordHash, totpSecret, status — KEIN FK auf User
  • AdminSession: eigene Tabelle, server-side, IP-gebunden
  • AdminRole/AdminPermission: eigenes RBAC-Schema
  • Kein Generalschlüssel zwischen Plattform-Admin und Mandanten-Welt
  • Magic-Link für Admin-Login verboten (AD-3)
  • AdminAuditLog: AuditEvent mit tenantId=null (nicht eine neue Tabelle)

C-04 — Session-Tabelle: Postgres als Source-of-Truth + Redis-Cache

type: protocol source: docs/ARCHITECTURE-DECISIONS.md (AD-4)

  • Session: server-side in Postgres; Felder: device_info (Browser/IP/Standort), last_activity_at
  • Inaktivitäts-Timeout: 4 Stunden; Sliding-Window: 30 Tage
  • Auto-Revoke aller Sessions bei: Passwort-Änderung, 2FA-Änderung, Email-Änderung
  • Cookie enthält ausschließlich Session-ID-Referenz (kein JWT, kein Session-Payload im Cookie)
  • Redis: schnelle Pro-Request-Validierung; NICHT alleinige Session-Source

C-05 — Such-Engine: Meilisearch + pgvector + RRF

type: nfr source: docs/ARCHITECTURE-DECISIONS.md (AD-5), _bmad-output/specs/M24-globale-suche.md

  • Meilisearch (self-hosted): Keyword-Suche; BP-Paket @hivegrid/search weitgehend 1:1 übernommen
  • pgvector: Semantische Suche; Embedding-Dimension 1024 (Scaleway EU-Endpoint)
  • Fusion: RRF (Reciprocal Rank Fusion) kombiniert beide Ergebnislisten
  • SearchIndexEntry muss tenant_id enthalten; Abfragen stets permission-aware (RLS + Permission-Filter)
  • Outbox-Pattern für asynchrone Indexierung nach Mutations

C-06 — Envelope-Encryption: Per-Tenant-DEK + Scaleway Key Manager

type: schema source: docs/ARCHITECTURE-DECISIONS.md (AD-8), _bmad-output/specs/M14-hr-hub.md

  • Pro Mandant ein Data-Encryption-Key (DEK), verschlüsselt via Scaleway Key Manager
  • Verschlüsselte Felder: OAuth-Tokens (M09/M12/M25), Payslips (M14), Passwort-Safe-Einträge (M14), Admin-TOTP-Secrets (M37), KWP-ApiKey (M19)
  • Algorithmus: AES-256-GCM
  • Crypto-Shredding bei Tenant-Löschung: DEK löschen → alle verschlüsselten Felder des Tenants unlesbar
  • Globaler Key (Boilerplate-Default) ist unzulässig für diese Felder

C-07 — Realtime-Protokoll: WebSocket für Chat, SSE für Updates

type: protocol source: docs/ARCHITECTURE-DECISIONS.md (AD-9)

  • Team-Chat (M13): WebSocket-Rooms (bidirektional); Presence, Typing-Indicator, Read-Receipts
  • Kanban-Updates (M03), Notifications (M22): SSE (server-sent, einseitig)
  • hocuspocus: ausschließlich für CRDT-Kollaboration (Dokumente), nicht für Chat-Broadcast
  • Redis-Pub/Sub für WebSocket Scale-Out

C-08 — Paket-Naming: @hivegrid/* ohne Alt-Aliase

type: protocol source: docs/ARCHITECTURE-DECISIONS.md (AD-10), docs/INTEGRATION-CONTRACTS.md

  • @hivegrid/*: einheitlicher Scope fuer alle Workspace-Pakete
  • packages/ui-app (nicht ui-hivegrid): HiveGrid-UI-Shell
  • apps/web/app/application/sidebar/: Sidebar-Konfiguration (nicht sidebar.config.ts)
  • packages/search/: Such-Index / indexedEntities (nicht packages/db/src/search/indexed-entities.ts)
  • keine Alt-Scope-Package-Aliase, kein altes CLI-Binary, keine parallelen technischen Produkt-Contracts

C-09 — Integration-Contracts: Sidebar-Wiring Pflicht

type: api-contract source: docs/INTEGRATION-CONTRACTS.md

  • Jeder neue Modul-Bereich MUSS in apps/web/app/application/sidebar/ registriert werden
  • SidebarEntry-Felder: id (kebab-case, unique), group (6 feste Gruppen), label (i18n-Key), icon (lucide-react), route, permission, badge?, order, feature_flag?
  • Funktion ohne Sidebar-Eintrag: nicht akzeptiert (kein anderer Einstiegspunkt ohne Begründung)
  • 6 Gruppen: arbeiten | stammdaten | kommunikation | automation-ki | personal | einstellungen

C-10 — Integration-Contracts: Route-Patterns

type: api-contract source: docs/INTEGRATION-CONTRACTS.md

Verbindliche URL-Schemata (Abweichungen erfordern Change-Request):

  • Mandanten-App: app.hivegrid.de/{modul}/... (Tenant aus Session/Cookie, NICHT im Pfad-Segment)
  • Mandant-Settings: app.hivegrid.de/settings/{modul}/...
  • Plattform-Admin: admin.hivegrid.de/{bereich}/...
  • Customer-Portal: app.hivegrid.de/portal/{tenant}/...
  • Public-Forms: app.hivegrid.de/f/{tenant}/{slug}
  • Public-Booking: app.hivegrid.de/b/{tenant}/{slug}
  • Public-Help: app.hivegrid.de/help/{lang}/{kategorie}/{slug}
  • Public-API: api.hivegrid.de/v1/{resource}
  • MCP-Server: mcp.hivegrid.de

C-11 — Integration-Contracts: Activity-Stream-API

type: api-contract source: docs/INTEGRATION-CONTRACTS.md

Pflicht-API für jede schreibende Aktion mit Entitäts-Bezug:

import { logActivity } from '@hivegrid/activity';
await logActivity({
  tenantId, actorId, actorType: 'user' | 'auto' | 'sync' | 'system',
  entityType, entityId,
  type: 'contact.created' | 'deal.stage_changed' | ...,
  payload: { ... },
});

Trennung: logActivity() ist NICHT der Audit-Eintrag (Audit = Prisma-Middleware separat)


C-12 — Integration-Contracts: Notification-API

type: api-contract source: docs/INTEGRATION-CONTRACTS.md

Kein direkter Email/Push-Versand aus Modulen. Immer:

import { notify } from '@hivegrid/notifications';
await notify({
  tenantId, recipientId,
  category: 'lead.received' | 'deal.won' | ...,
  template: 'lead-received',
  payload: { ... },
  priority: 'normal' | 'high' | 'urgent',
});

Service (M22) entscheidet Kanal, Bündelung, Ruhezeiten.


C-13 — Integration-Contracts: Permission-Keys-Schema

type: api-contract source: docs/INTEGRATION-CONTRACTS.md

  • Permission-Definitionen ausschließlich in packages/entitlements/src/permissions.ts
  • Format: {modul}.{action} oder {modul}.{action}_{scope}
  • Sidebar-Einträge, Routes, View-Models, Actions filtern alle gegen diese Keys
  • Permission-Check: server-side (Pflicht) + client-side hide (zusätzlich, nie alleinig)

C-14 — Integration-Contracts: Search-Index-Registration

type: api-contract source: docs/INTEGRATION-CONTRACTS.md (§8), docs/ARCHITECTURE-DECISIONS.md (AD-10)

  • Neue suchbare Entität MUSS in packages/search/ (indexed-entities.ts) registriert werden
  • Format: { table, searchable: string[], permission: string }
  • Permission-aware-Search (M24) liest diese Map

C-15 — Integration-Contracts: i18n-Key-Schema

type: api-contract source: docs/INTEGRATION-CONTRACTS.md (§9)

  • Locale-Files: packages/i18n/src/locales/de/{modul}.json
  • Naming: {modul}.{bereich}.{key} (Pflicht-Format)
  • ESLint-Rule blockt JSX-Text-Nodes ohne t()
  • Build-Lint blockt Hard-Strings im Build

C-16 — Integration-Contracts: View-Model-Pflicht pro Route

type: protocol source: docs/INTEGRATION-CONTRACTS.md (§11)

  • Jede Route in app/routes/** baut im Loader ein View-Model
  • UI-Components in packages/ui-app/** empfangen NUR das VM + Action-Callbacks
  • Kein direkter Store/DB-Zugriff in UI-Components

C-17 — Integration-Contracts: Smoke-Test-Pflicht pro Route

type: nfr source: docs/INTEGRATION-CONTRACTS.md (§12)

  • Jede neue Route: Smoke-Test in e2e/smoke/{modul}.spec.ts
  • Smoke-Tests laufen gegen packages/ui-mock
  • Schlagen Smoke-Tests mit ui-mock fehl → Hot-Swap-Architektur verletzt

C-18 — Audit-Hash-Kette: Tamper-Nachweis

type: schema source: _bmad-output/specs/M21-audit-log.md

  • AuditEntry.current_hash = SHA256(previous_hash + payload)
  • Append-only-Constraint auf Tabelle (kein UPDATE/DELETE erlaubt)
  • AuditEntry mit tenantId=null = plattformweiter Eintrag (auch für AdminAuditLog)

C-19 — KWP-Datenbank-Credentials: NICHT in Cloud gespeichert

type: schema source: _bmad-output/specs/M19-kwp-integration.md

  • KwpSettings.kwp_db_host, kwp_db_port, kwp_db_name: lokal vom kwpsync.exe verwaltet
  • Diese Felder werden aus DSGVO-Gründen NICHT in der HiveGrid Cloud gespeichert
  • Nur KwpApiKey (Token für Cloud-Auth) wird verschlüsselt in Cloud gespeichert (AD-8)

C-20 — EU-Stack: LLM-Provider ausschließlich EU-ansässig

type: nfr source: docs/ARCHITECTURE-DECISIONS.md (Scope-Items LP-13), _bmad-output/specs/M18-ki-layer.md

  • KI-Anfragen nur an EU-Provider: Scaleway, Mistral, AlephAlpha
  • OpenAI/Anthropic/US-Provider verboten (LP-13)
  • Embedding-Dimension: 1024 (Scaleway EU-Endpoint)
  • Promptfoo für Sicherheits-Testing der KI-Ausgaben

C-21 — BullMQ: asynchrone Queue für Versand und Jobs

type: protocol source: _bmad-output/specs/M10-email-marketing.md, _bmad-output/specs/M22-notifications.md, _bmad-output/specs/M35-dsgvo-export.md

  • Email-Marketing-Versand: BullMQ-Queue (async, Rate-Limit konfigurierbar)
  • Notification-Versand: BullMQ-Pipeline oder Novu-Middleware
  • DSGVO-Export-Jobs: BullMQ-Worker (async ZIP-Generierung)
  • Redis als BullMQ-Backend

C-22 — API-Keys: SHA-256-Hash gespeichert, Key nur einmalig angezeigt

type: schema source: _bmad-output/specs/M27-auth-multi-tenancy.md, _bmad-output/specs/M34-public-api.md

  • ApiKey.key_hash = SHA-256 des Klartext-Keys
  • Klartext-Key nur bei Erstellung angezeigt, danach nicht mehr abrufbar
  • Public-API Rate-Limit: 1000 Req/Min Default (Redis-backed)
  • Outgoing-Webhooks: Signatur via HMAC-SHA256 im X-HiveGrid-Signature-Header

C-23 — Offline-Sync: KWP-gewinnt Conflict-Resolution

type: protocol source: docs/ARCHITECTURE-DECISIONS.md (AD-17), _bmad-output/specs/M36-mobile-app.md

  • Mobile-Offline: OfflineSyncQueue mit entity_type, operation, payload, conflict_resolution
  • Conflict-Resolution-Regel: "KWP gewinnt" bei KWP-Sync-Konflikten
  • HiveGrid-interne Konflikte: Last-Write-Wins
  • Offline-Indikatoren: Klartext-Hinweis in App (kein stilles Versagen)

C-24 — Customer-Portal: Default-Sichtbarkeit NICHT sichtbar

type: protocol source: docs/ARCHITECTURE-DECISIONS.md (AD-18), docs/INTEGRATION-CONTRACTS.md (§14)

  • Neue Funktionen für Customer-Portal sind standardmäßig NICHT sichtbar
  • Explizite Freigabe durch Tenant-Admin erforderlich (CustomerPortalProjectDocument, PortalConfiguration)
  • Registrierung in packages/ui-app/src/customer-portal/portal-shell.config.ts

C-25 — Node-Version-Constraint

type: nfr source: memory/project_node_version_toolchain.md

  • Development + Test: Node 22.12.x (nicht 20.x)
  • Runtime (Produktiv): node:20
  • .nvmrc auf 22.12.x gesetzt
  • Begründung: undici/Prisma/localstorage-Kompatibilität