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

247 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# HiveGrid Intel — Architecture Decisions (ADR Extraction)
source: docs/ARCHITECTURE-DECISIONS.md
locked: true (AD-1 through AD-5, AD-8 through AD-19 are Accepted/binding; AD-6 and AD-7 are 🅿️ Backlog — NOT locked)
extracted: 2026-06-07
---
## AD-1 — Mandanten-Trennung: echtes Postgres-RLS
status: Accepted (locked)
scope: tenant isolation, alle tenant-scoped Module
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Row-Level-Security in Postgres als bauliche Vorgabe (nicht nur App-Level-Scoping).
- RLS-Policies (USING/WITH CHECK) als Forward-Migration mit Inverse-SQL-Kommentar
- Request-Middleware setzt `SET LOCAL app.tenant_id`
- App-DB-Rolle ohne `BYPASSRLS`
- Worker-/Job-Tenant-Context-Wrapper
- Cache-Präfix `tenant:{id}:`, S3-Pfad `tenants/{id}/`
- Ausnahmen ohne RLS: `users`, `subscription_*`, `feature_flags`, Branchen-Templates
Betrifft: M019 + jedes tenant-scoped Modul (M01–M39 außer Plattform-Admin-Tabellen)
---
## AD-2 — Daten-Modell: typisierte Tabellen, Entity-Builder raus
status: Accepted (locked)
scope: CRM-Datenmodell, Fachentitäten
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: HiveGrid-Fachentitäten (CRM, Deals, Aufträge, Tasks, …) als dedizierte, typisierte First-Class-Prisma-Tabellen. Das Entity-Builder-CRM der Boilerplate (`Entity`+`Row`+`RowValue`, `apps/web/app/modules/crm`) wird entfernt, nicht angepasst. Custom-Felder über purpose-built `CustomFieldDefinition` + `CustomFieldValue` (JSONB-Wert), nicht über die polymorphe Row-Engine.
Betrifft: M01, M02, M03, M04, M26 + alle Fachmodule
---
## AD-3 — Plattform-Admin-Identität: getrennt, Email+PW+TOTP, optional Authentik-SSO
status: Accepted (locked)
scope: AdminUser, AdminSession, admin.hivegrid.de
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Vollständig getrennte Admin-Welt — eigene `AdminUser`-Tabelle (eigenes `passwordHash`/`totpSecret`/`status`), eigene `AdminSession` (server-side, IP-gebunden), eigene `AdminRole`/`AdminPermission`-RBAC. Primärer Login: Email + Passwort + TOTP (Magic-Link verboten). Zusätzlich optionaler Authentik-OIDC/SSO-Login, gemappt auf dieselbe getrennte Admin-Identität. Kein Generalschlüssel zwischen Plattform und Mandanten.
- `AdminAuditLog` nutzt vorhandenen `AuditEvent` (Hash-Kette, `tenantId=null` = plattformweit)
Betrifft: M034–M041 (M37)
---
## AD-4 — Sessions: Postgres als Source-of-Truth + Redis-Cache
status: Accepted (locked)
scope: Session-Management, alle Auth-Flows
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Server-side Session-Tabelle in Postgres (Geräte-Liste mit Browser/IP/Standort/letzter Aktivität, Revoke, „von allen Geräten abmelden", 4h-Inaktivität, 30-Tage-Sliding-Window, Auto-Logout bei Passwort-/2FA-/Email-Änderung) als Quelle der Wahrheit; Redis-Cache für schnelle Pro-Request-Validierung. Cookie hält nur die Session-ID-Referenz.
Betrifft: M021 (Mandanten-User), M034 (AdminSession), M141/M15 (Customer-Portal)
---
## AD-5 — Such-Engine: Meilisearch (self-hosted) + pgvector-Hybrid
status: Accepted (locked)
scope: Globale Suche, Search-Infrastruktur
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Keyword-Suche über selbst gehostetes Meilisearch (BP-`@hivegrid/search` weitgehend 1:1), semantische Suche über pgvector + EU-Embeddings (Scaleway 1024-dim, BP 1:1), kombiniert via RRF-Fusion. Embedding-Pipeline + Outbox + Indexer-Worker aus der BP übernehmen.
Hinweis: Weicht bewusst von M056 "Postgres-FTS, kein Extra-Service" ab → Change-Request gegen M056 nötig.
Betrifft: M24 / M056–M058
---
## AD-6 — EU-Email-Provider
status: BACKLOG — NICHT LOCKED (🅿️ Entscheidung später)
scope: Transaktions- und Marketing-Email
source: docs/ARCHITECTURE-DECISIONS.md
Tendenz: Mailjet (EU/FR). MailerSend (BP-Default) ist vertretbar (EU ISO 27001 + GDPR-DPA), Caveat: US-Entität. Alternativen: Mailjet/Brevo, Scaleway TEM.
Betrifft: M09, M10, M22
---
## AD-7 — Captcha / Bot-Schutz
status: BACKLOG — NICHT LOCKED (🅿️ Entscheidung später)
scope: Login, Public-Forms, Booking
source: docs/ARCHITECTURE-DECISIONS.md
Tendenz: EU — Friendly Captcha (DE) oder self-hosted mCaptcha. Turnstile (BP) und hCaptcha (Spec) sind beide US-Firmen.
Betrifft: Login (M020), Public-Forms (M05/M125), Booking (M06)
---
## AD-8 — Verschlüsselung: Per-Tenant-DEK + Envelope
status: Accepted (locked)
scope: Verschlüsselung, HR-Passwort-Safe, OAuth-Tokens, DSGVO-Löschung
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Pro Mandant ein Data-Encryption-Key (DEK), verschlüsselt mit einem Master-Key (Scaleway Key Manager) — Envelope-Encryption. Crypto-Shredding bei Mandanten-Löschung (Tenant-Key wegwerfen → alle verschlüsselten Daten unlesbar).
Betrifft: M14/M134 (HR-Passwort-Safe), OAuth-Tokens (M09/M25/M12), M35/M165 (DSGVO-Löschung)
---
## AD-9 — Realtime: WebSocket für Chat + SSE für Read-Updates
status: Accepted (locked)
scope: Realtime-Infrastruktur, Team-Chat, Kanban, Notifications
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Generischer WebSocket-Room-Layer für bidirektionale Echtzeit (Team-Chat M13: Rooms, Presence, Typing, Read-Receipts). SSE bleibt für einseitige Live-Updates (Kanban M03, Notifications M22). `hocuspocus` bleibt CRDT-only (Kollab-Dokumente).
Betrifft: M13 (bidirektional WebSocket); SSE-Pfad: M03, M22
---
## AD-10 — Naming-Konvention: HiveGrid-Scope ohne Alt-Aliase
status: Accepted (locked)
scope: Paket-Naming, Mono-Repo-Struktur, alle Module
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Alle Workspace-Pakete und technischen Produkt-Contracts nutzen HiveGrid-Namen:
`@hivegrid/*`, `hivegrid-cli`, `HIVEGRID_*`, `hivegrid_*`-Cookies, `x-hivegrid-*`-Header und
`hivegrid.*`-Queue-Namen. Es gibt keine Alt-Aliase.
- `packages/ui-app`, `packages/ui-subframe`, `packages/ui-mock` behalten ihre realen Pfade
- Estate-Slugs bleiben externe Infrastruktur (`git.tool-ctrl.de`, `toolctrl-labs`, `toolctrl-ci`, Plane-Workspace `toolctrl`)
- Docs: wo "ui-hivegrid", Alt-Scopes oder alte Sidebar-Pfade stehen, ist das Doku-Drift
Betrifft: Querschnitt (alle Module), Phase 0
---
## AD-11 — Bau-Strategie: Hybrid (Fundament-Kern, dann Geerkens-Kernpfad)
status: Accepted (locked)
scope: Delivery-Sequenzierung
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Nach Phase 0 zuerst Fundament-Kern (M27 Auth + M33a Apps-Engine + M01 CRM-Datenmodell), dann sofort Geerkens-Wertschöpfungskette Lead → Sales → Auftrag → KWP, danach Breite (HR, Portal, Marketing, Mobile, Billing).
---
## AD-12 — SHK-Domänen-Defaults: aus Spec als Seed, Noah validiert
status: Accepted (locked)
scope: SHK-Branchen-Templates, Seeding
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: SHK-Inhalte (6 Standard-Rollen + Permission-Bundles, SHK-Sales-Pipeline-Stufen, Standard-Custom-Felder + Tags, Provisionierungs-Daten) werden als deklaratives, leicht änderbares Seed umgesetzt. Noah/Geerkens validieren iterativ. Blockiert den Bau nicht.
---
## AD-13 — Go-Live-Scope: breiter Launch
status: Accepted (locked)
scope: Delivery-Scope
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Erster Geerkens-Go-Live umfasst nicht nur die Vertriebskette, sondern auch HR-Hub, Customer-Portal, Marketing und Mobile. Scope ≈ Großteil der 35 Module. Sequenzierung trotzdem nach AD-11.
---
## AD-14 — Migration: sauberer Start + KWP-Sync füllt nach
status: Accepted (locked)
scope: Datenmigration, KWP-Sync
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Geerkens startet weitgehend leer; KWP-Sync bringt Auftrags-/Stammdaten automatisch. HubSpot/Quiply-Altdaten bleiben extern als Read-only-Archiv; nur punktuelle CSV-Importe. Keine vollen Migrations-Pipelines pro Quelle zum Launch.
---
## AD-15 — Pricing/Billing: Engine bauen, Preise geparkt
status: Accepted (locked)
scope: Legacy-Provider, Billing-Engine, Pricing
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Legacy-Provider-Integration + Seat-/Plan-Engine + Verbrauchs-Metering werden technisch gebaut, die konkreten Preis-Stufen bleiben geparkt. Geerkens läuft auf manueller Sonderkondition/Trial. Self-Service-Checkout-Preise = eigene spätere Pricing-Runde.
---
## AD-16 — USP-Säulen (Automation + KI): volle Tiefe zum Launch
status: Accepted (locked)
scope: Automation-Engine M17, KI-Layer M18
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Kompletter visueller Automation-Editor (alle Trigger/Aktionen, 24h-Undo, Guards) und voller KI-Layer (EU-Provider, RAG, Sprach-zu-Automation, Pay-as-you-go) sind day-1 dabei — nicht nur Fundament.
---
## AD-17 — Mobile-Offline: voller Offline-Betrieb
status: Accepted (locked)
scope: Mobile-App M36, Offline-Sync
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Monteur kann auf der Baustelle offline Aufträge bearbeiten, Abnahmen erfassen, Plantafel sehen; alles wird gequeued + bei Sync mit „KWP gewinnt" aufgelöst.
---
## AD-18 — Customer-Portal: voll inkl. Skalierungs-Sicht
status: Accepted (locked)
scope: Customer-Portal M15
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Komplettes Portal day-1: Projekt-Sicht + Upload + Reklamation + Subunternehmer-Zugang + Skalierungs-Sicht (Service-Inbox + Routing + Pro-Kunden-Lebensdauer).
---
## AD-19 — Go-Live-Modus: Big-Bang
status: Accepted (locked)
scope: Go-Live-Strategie
source: docs/ARCHITECTURE-DECISIONS.md
Entscheidung: Geerkens geht erst live, wenn das vollständige Phase-1-Produkt steht — ein großer Launch, kein phasiertes Produktiv-Go-Live. Interne Bau-Reihenfolge bleibt AD-11.
Bewusst akzeptiert: längste Zeit bis zum ersten echten Nutzer-Feedback, höchstes Risiko. Gegenmaßnahme: Noah/Geerkens-Validierung pro Modul über PROGRESS-TRACKER-Klick-Pfad als Feedback-Ersatz.
---
## Phase-0-Pflichten (Voraussetzungen, keine ADR-Entscheidungen)
source: docs/ARCHITECTURE-DECISIONS.md
1. Codebase lauffähig halten
2. Naming-Drift beheben: HiveGrid-Contracts in Code und Docs, Sidebar-Konvention korrigieren
3. EU-Sterilisation: GitHub/Google-OAuth-Reste + `User.githubId/googleId` entfernen
4. M00 aktivieren + 4 echte Neubauten: `logActivity()`/Activity-Stream, Search-Registry, Subframe-Adapter-Code, Mass-Action-Schutz
5. Fehlende Dependencies ergänzen: `signature_pad`, `browser-image-compression`, `react-grid-layout`, `@dnd-kit`, `libphonenumber`, `ics`/`ical-generator`, `btree_gist`/`EXCLUDE`-Constraint u.a.
## KWP-API-Entscheidung (separater Strang)
source: docs/ARCHITECTURE-DECISIONS.md
KWP bekommt eine offizielle API-Anbindung → M089 (Windows-Sync-Programm) entfällt, M090/M091/M092/M094/M095 vereinfachen sich, M093 bleibt. KWP als `DataConnection type='rest-api'` ins Apps-Engine-Muster (M33a). M089–M095 vor Umsetzung neu schneiden.