327 lines
11 KiB
Markdown
327 lines
11 KiB
Markdown
# 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
|