5.6 KiB
HiveGrid Intel — Context Notes
Supporting notes from DOC-type sources and cross-cutting SPEC metadata. extracted: 2026-06-07
Topic: Projekt-Überblick und Ziel
source: docs/ARCHITECTURE-DECISIONS.md
HiveGrid 2.0 ist eine SaaS-Plattform für SHK-Handwerksbetriebe (Sanitär, Heizung, Klima). Erstkunde: Geerkens GmbH. Das Produkt löst ab: HubSpot (CRM + Sales-Pipeline), Quiply (Team-Chat), Zapier/n8n (Automation), sowie mehrere Excel-Prozesse.
Die Codebase ist ein Git-Downstream der ToolCTRL-Boilerplate (upstream-Remote bleibt erhalten). Boilerplate deckt ~35–45 % der Anforderungen ab (Fundament high, Fachdomäne greenfield).
USP-Säulen (Day-1-Launch): Automation-Engine (visuell, KI-gestützt) + KI-Layer (EU-only) + KWP-Integration (Kern-ERP Geerkens).
Topic: Phase-0-Pflichten (vor Fachmodul-Bau)
source: docs/ARCHITECTURE-DECISIONS.md
Die folgenden Voraussetzungen sind vor dem ersten Fachmodul-Bau abzuarbeiten:
- Boilerplate einziehen (Repo ist aktuell Docs-only, keine echte Codebase)
- Naming-Drift in Docs beheben (AD-10)
- EU-Sterilisation: GitHub/Google-OAuth-Reste entfernen
- M00 aktivieren + 4 Querschnitts-Neubauten (logActivity, Search-Registry, Subframe-Adapter, Mass-Action-Schutz)
- Fehlende Dependencies eintragen (PLAN.md teils falsch)
Topic: Delivery-Sequenzierung (AD-11)
source: docs/ARCHITECTURE-DECISIONS.md
Reihenfolge:
- Phase 0 (Voraussetzungen, oben)
- Fundament-Kern: M27 (Auth) → M33a (Apps-Engine) → M01 (CRM-Datenmodell)
- Geerkens-Kernpfad: M02 (Lead-Inbox) → M03 (Sales) → M04 (Auftrag) → M19 (KWP)
- Breite: HR-Hub (M14), Customer-Portal (M15), Marketing (M10), Mobile (M36), Billing-Feinheiten (M28)
Go-Live: Big-Bang (AD-19) — kein phasiertes Produktiv-Schalten. Gegenmaßnahme: Noah/Geerkens-Validierung per PROGRESS-TRACKER-Klick-Pfad.
Topic: SHK-Branchen-Kontext
source: _bmad-output/specs/M01-crm-kern.md, M03-sales-pipeline.md, M04-auftragspipeline.md
Geerkens ist SHK-Betrieb (Heizungsanlagen, Wartung, Reparatur). Typische Entitäten:
- Kunden (B2C + B2B) mit Anlagen-Zustand (Custom-Felder)
- Vertriebsfälle: Anlagen-Verkauf (mehrstufig), Wartungsverträge (kürzer), Reparatur-Aufträge (direkt zu M4)
- KWP: Windows-basiertes ERP mit MSSQL; HiveGrid synchronisiert bidirektional
- Monteure: arbeiten auf Baustellen, brauchen Offline-Zugriff (AD-17)
- Noah = Geerkens-Kontakt für Validierung der SHK-Defaults
SHK-Seeds (beim Tenant-Anlegen): 6 Standard-Rollen, 2 Sales-Pipelines, Custom-Felder für Heizungsanlagen, Projekt-Pipelines, Automation-Templates, Onboarding-Branchen-Zweig.
Topic: Boilerplate-Reuse-Struktur
source: docs/ARCHITECTURE-DECISIONS.md (AD-10), docs/INTEGRATION-CONTRACTS.md
Boilerplate-Pakete (unveränderter Name, upstream-mergebar):
- packages/ui-app (UI-Shell)
- packages/ui-subframe (Subframe-Adapter)
- packages/ui-mock (Mock-UI für Hot-Swap-Tests)
- @toolctrl/search (Meilisearch-Paket)
- @toolctrl/foundation (Basis-Utilities)
Neue HiveGrid-Querschnittsdienste (zu bauen, @hivegrid/*-Namespace):
- @hivegrid/activity (logActivity-Service + zentrale Activity-Tabelle)
- @hivegrid/audit (auditEvent-Service)
- @hivegrid/notifications (notify-Service)
- packages/entitlements (Permission-Keys-Registry)
- packages/search (indexed-entities.ts für suchbare Entitäten)
- packages/i18n (Locale-Files)
Topic: KWP-Recut-Entscheidung
source: docs/ARCHITECTURE-DECISIONS.md (KWP-Abschnitt), memory/project_kwp_api_anbindung.md
KWP bietet inzwischen eine offizielle API an. Das hat Konsequenzen:
- M089 (Windows-Sync-Programm kwpsync.exe) entfällt
- M090/M091/M092/M094/M095 vereinfachen sich erheblich
- M093 (Schema-Drift-Sentinel) bleibt relevant
- KWP wird als DataConnection type='rest-api' (statt 'windows_client') in M33a geführt
M089–M095 müssen VOR Umsetzung neu geschnitten werden. Die aktuelle M19-Spec beschreibt noch die Windows-Client-Variante.
Topic: Spec-Stil-Vorgabe
source: memory/feedback_spec_style_no_ui.md
Alle Specs verwenden "requirements-pur"-Stil:
- UI-Elemente als Liste beschrieben (benötigte Komponenten), keine ASCII-Layouts
- Designer hat freie Hand für konkrete Anordnung/Layout
- Spezifiziert: was angezeigt werden muss + welche Operationen, NICHT wie es aussieht
Topic: Offene Entscheidungen (noch nicht getroffen)
source: docs/ARCHITECTURE-DECISIONS.md (AD-6, AD-7)
AD-6 — EU-Email-Provider (Backlog):
- Tendenz Mailjet (EU/FR)
- MailerSend (BP-Default) vertretbar aber US-Entität (LP-13-Risiko)
- Alternativen: Brevo, Scaleway TEM
- Betrifft: M09, M10, M22
AD-7 — Captcha/Bot-Schutz (Backlog):
- Tendenz Friendly Captcha (DE) oder self-hosted mCaptcha
- Turnstile (BP) und hCaptcha sind US-Firmen
- Betrifft: Login, Public-Forms (M05), Booking (M06)
Topic: Spec-Status
source: alle _bmad-output/specs/M*.md
Alle 36 Modul-Specs haben status: detail-spec-draft. Vor Bau jedes Moduls:
- Verifizierung mit Noah (Geerkens-Repräsentant)
- Konkrete Index-Definitionen + Migrations-SQL ergänzen
- SHK-Default-Werte finalisieren
- Subframe-UI-Designs (separat, nicht in Spec)
Topic: Cross-Ref-Graph (Zusammenfassung)
source: alle .json Klassifizierungs-Dateien
Keine Zyklen im 38-Dokument-Graph (Cycle Detection: DFS three-color marking — alle Refs einseitig). Externe Refs auf nicht-klassifizierte Dokumente (AGENTS.md, brainstorming-session-2026-05-07-2206.md, Milestone-PLAN-Dateien, M11-whatsapp.md) — diese sind nicht im Ingest-Set, stellen aber keine Zyklen dar.
M13 referenziert M11-whatsapp.md (nicht im Set — Phase 2 Modul, nicht klassifiziert). Kein Blocker. M18-ki-layer.md referenziert M11-whatsapp.md (nicht im Set). Kein Blocker.