# 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 @toolctrl/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: @toolctrl/* bleibt, @hivegrid/* nur für neue Querschnittsdienste type: protocol source: docs/ARCHITECTURE-DECISIONS.md (AD-10), docs/INTEGRATION-CONTRACTS.md - @toolctrl/*: Boilerplate-Pakete, unveränderter Name (upstream-mergebar) - 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) - @hivegrid/*: nur neue, genuin HiveGrid-eigene Pakete (z.B. @hivegrid/activity, @hivegrid/audit, @hivegrid/notifications) --- ## 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: app.hivegrid.de/api/v1/{resource} --- ## 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