Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/handouts/raffael/HANDOUT-RAFFAEL.md
T

19 KiB
Raw Blame History

pdf_options, css
pdf_options css
format margin
A4 16mm
body { font-size: 10.5px; font-family: -apple-system, "Segoe UI", Helvetica, Arial, sans-serif; } h1 { font-size: 19px; } h2 { font-size: 14px; border-bottom: 2px solid #f5a623; padding-bottom: 3px; margin-top: 20px; break-after: avoid; page-break-after: avoid; } h3 { font-size: 12px; break-after: avoid; page-break-after: avoid; } table { font-size: 9.5px; border-collapse: separate; border-spacing: 0; width: 100%; border-top: 1px solid #ccc; border-left: 1px solid #ccc; } thead { display: table-header-group; } tr { break-inside: avoid !important; page-break-inside: avoid !important; } td, th { break-inside: avoid !important; border-right: 1px solid #ccc; border-bottom: 1px solid #ccc; padding: 3px 5px; vertical-align: top; } th { background: #fff7e8; } li { break-inside: avoid; } p { orphans: 3; widows: 3; } code { background: #f4f4f4; padding: 1px 3px; font-size: 9px; } .pagebreak { page-break-after: always; }

HANDOUT RAFFAEL: Lead-Dev

Mission: Kern-Kette (Lead → Sales → Auftrag) + beide USP-Säulen (Automation, KI) + technische Externals. v1 bis 10.07., dein v2-Anteil (17 MS, inkl. KWP) bis 31.07. Arbeitsrhythmus: Mo bis So, täglich mind. 8 h · 9:00 Dev-Sync mit Akeshan · Integration auf main täglich. Deine Gates: Fr 19.06. (W1, du führst) · Fr 26.06. (Noah-Demo 1, du präsentierst) · Fr 03.07. (Kette E2E) · Fr 10.07. (Go/No-Go).

Timeline auf einen Blick

Datum Paket
Fr 12. bis Di 16.06. AP-1: P1 Fundament (Stränge A+B) + Externals
Mi 17. bis Fr 19.06. AP-2: P2 Identität & Mandanten
Sa/So 20./21.06. AP-3: P5 Apps-Engine
Mo 22. bis Mi 24.06. AP-4: P6 CRM-Kern
Do/Fr 25./26.06. AP-5: P7 Lead-Inbox + [€] Preise fix (25.) + Noah-Demo 1
Sa bis Mo 27. bis 29.06. AP-6: P8 Sales-Pipeline + v2-Vorlauf-Externals (29.)
Di bis Do 30.06. bis 02.07. AP-7: P9 Projekte & Plantafel
Sa/So 04./05.07. AP-8: P11 Suche & Dashboard
Mo bis Mi 06. bis 08.07. AP-9: P12 Automation (USP)
Do 09.07. AP-10: P13 KI-Layer + FREEZE
Fr 10.07. [LAUNCH] Go/No-Go mit Noah
Mo 13. bis Fr 17.07. AP-11: KWP-Recut + Public-API + API-Keys
Sa/So 18./19.07. AP-12: HiveMind/RAG Start
Mo 20. bis So 26.07. AP-13: KWP gegen echte API
Mo 27. bis Fr 31.07. AP-14/15: AdminUser-Welt · HalloPetra · DSGVO-Auskunft

Schnittstellen: was du bekommst, was andere von dir brauchen

Du bekommst:

Von Was Wann
Akeshan Hot-Swap-Maschine + Walking-Skeleton (P1 Strang C) Di 16.06.
Akeshan Staging/CI läuft (Gates brauchen das) Mi 17.06.
Akeshan EntityLink-Tabelle aus P4 (brauchst du in P6 für Task-CRM-Links) Fr 19.06.
David Screen-Pakete: CRM 24.06. · Kanban 26.06. · Plantafel 01.07. · Flow-Editor + Dashboard 03.07. · KI-Panel 06.07. je Deadline
Noah KWP-Mail-Freigabe (12.06.) · SHK-Beispieldaten + Lagerist-Antwort (26.06.) · Demo-Teilnahme an den Gate-Freitagen siehe Daten
Partner Kostenmatrix-Input fürs Preis-Gespräch Do 25.06.
Haris Markt-Feedback aus den Calls (Einwände, fehlende Argumente) laufend ab 23.06.

Andere brauchen von dir:

Wer Was Wann
Akeshan Service-Kerne aus P1 (Audit, notify, Flags, i18n): er baut ab Mi alles darauf Di 16.06.
Akeshan Apps-Engine-Vertrag (P5): seine P14/P15/P16-Anbindungen laufen darüber So 21.06.
Akeshan CRM-Entitäten (P6): Marketing-Segmente + Chat-Verknüpfungen brauchen Contacts Mi 24.06.
Haris Preise (25.06.) · Stripe Payment Link (26.06.) · Live-Demo im Webinar (14./15.07.) siehe Daten
Dejan Rechtstexte vom Anwalt durchreichen · Preise für die Pricing-Seite sobald da / 25.06.
David Reconciliation-Feedback je Screen (passt jedes Feld zu einer Datenquelle?) < 24 h je Screen
Noah Demo-Führung an den Gate-Freitagen + KWP-E2E-Termin (24.07.) Gate-Freitage

Externals (nur du)

Wann Was
Fr 12.06. KWP-Antwortmail (Callback-URLs) · bnWin 8.1 N3 an Noah · AVV + Rechtstexte an Anwalt
Mo 15.06. Mailjet-DNS + Warm-up · Google-Calendar-OAuth · Stripe-Live · AirCall/PandaDoc-Sandbox · Hetzner-Projekt HiveGrid + Mistral-Key · Noah-Slots blocken
Do 25.06. [€] Kostenmatrix/Preise mit Partner FIX (Blocker für Haris!)
Mo 29.06. Web-Push-VAPID-Keys · Gmail-Restricted-Scope-Antrag · Microsoft-Entra-App (Google Play Console / FCM/APNs entfallen — PWA-only, AD-17)
Mo 13.07. HalloPetra-Konto · Memberspot-Zugänge

AP-1: P1 Fundament, Stränge A+B (Fr 12. bis Di 16.06.)

Was: Die Service-Kerne und Verträge, auf denen alles andere steht. Akeshan baut parallel Strang C (Hot-Swap-Maschine). Fertig heißt: Boilerplate-Ist-Stand dokumentiert (ADR-Text veraltet, Code ist seit 04.06. real!) · EU-Sterilisation durch (GitHub/Google-OAuth-Reste + GA/ConvertKit raus) · alle Service-Kerne als aufrufbare Dienste mit Smoke-Test · tenantHasModule()-Gate am Skeleton demonstrierbar · URL-Schemata dokumentiert.

Milestone Inhalt (1 Zeile)
M001 audit-log-default Jede Mutation erzeugt automatisch einen AuditEvent (Prisma-Middleware, SHA-256-Hash-Kette), default-on
M002 klartext-diagnostik Fehler-Katalog: jeder Fehler hat deutschen Klartext + Lösungs-Knopf; ESLint verbietet nacktes throw
M003 i18n-pflicht-wiring Jeder String läuft durch t(), verify:i18n-CI-Gate, v1 nur DE-Locale (vollständig)
M004 tenant-scope-owner-check withTenantScope/withOwnerCheck als Pflicht-Wrapper für jeden Datenzugriff
M005 url-tampering-schutz IDs in URLs werden server-seitig gegen Tenant geprüft; Mass-Action-Schutz (Limit + Bestätigung)
M006 feature-flag-engine tenantHasFlag() + Redis-Cache + plan-tier-Targeting; Grundlage der Konnektor-Pflicht
M007 idempotenz-wrapper Doppelt gefeuerte Jobs/Webhooks führen nicht zu Doppel-Daten (Idempotency-Keys)
M011 notification-service notify({channel, recipient, template}) als Pflicht-Interface; Kanäle In-App + Email, Push ruht
M176 anti-liste-doku Die Anti-Liste (was wir bewusst NICHT bauen) als Change-Request-Doku im Repo

AP-2: P2 Identität & Mandanten (Mi 17. bis Fr 19.06.)

Was: Signup, Login, echte Mandanten-Trennung. Boilerplate HIGH-Coverage (Login/Magic-Link/TOTP fertig); dein Eigenbau-Kern ist RLS. Fertig heißt (= Gate W1): Self-Service-Signup → Tenant mit Auto-SHK-Seed · Login + TOTP + Server-Sessions · RLS-Cross-Tenant-Beweis (nachweisbar kein Fremd-Zugriff, AD-1) · 6 SHK-Rollen geseedet.

Milestone Inhalt
M018 mandanten-anlage Signup mit Auto-Slug (Reserved-Words geblockt), Tenant-Provisionierung
M019 trennung-hardening Postgres-RLS: USING/WITH CHECK, SET LOCAL app.tenant_id, App-Rolle ohne BYPASSRLS + Beweis-Test
M020 email-passwort-auth NIST-Regeln, HaveIBeenPwned-Breach-Check, mCaptcha ab 3. Fehlversuch (zentral, nur ENV)
M021 magic-link-sessions Magic-Link + Server-Sessions in Postgres (Geräte-Liste, Revoke, „überall abmelden") + Redis-Cache
M022 totp-2fa TOTP (RFC 6238) mit QR-Setup, Trust-Device 30 Tage (Boilerplate liefert fast alles)
M023 rollen-engine Role/Permission-System + 6 SHK-Standard-Rollen + Gruppen
M024 einladung-deaktivierung Einladung (48h-Token), Soft-Deaktivierung mit Reassign-Workflow für offene Verknüpfungen
M025 konto-loeschung DSGVO-Löschung via PII-Anonymisierung ohne Audit-Trail-Verlust (Boilerplate-Muster)
M026 mandanten-lebenszyklus Tenant-Status-Maschine (trial/active/past_due/frozen/…) + Status-Banner; liest Subscription-Stub

(M027 API-Keys ist v2, wandert mit der Public-API.)

AP-3: P5 Apps-Engine (Sa/So 20./21.06.)

Was: DER Integrations-Vertrag. Alles Externe (AirCall, PandaDoc, Stripe, Google, später KWP) läuft über dieses eine Framework. Fertig heißt: Eine DataConnection lässt sich per OAuth ODER API-Key herstellen, Status-Ampel + Klartext, Health-Check, Tokens verschlüsselt (DEK aus Coolify-Secret).

Milestone Inhalt
M008 adapter-state-machine DataConnection-Modell + Status-Maschine (pending/active/degraded/broken/revoked) + Adapter-Registry (typsicher erweiterbar)
M009 setup-wizard-sync-log Connect-Wizard (Voraussetzungen → Credentials → Health-Check) + AppSyncRun-Log mit Klartext
M010 probe-scheduler-webhook-schutz Periodische Health-Probes + HMAC-Signaturprüfung für eingehende Webhooks

AP-4: P6 CRM-Kern (Mo 22. bis Mi 24.06.)

Was: Das Datenfundament des Produkts. Mi Abend fertig = Davids CRM-Screens docken an, Noah-Demo 1 am Fr. Fertig heißt: Kontakt/Firma anlegen, finden, verknüpfen; Custom-Felder mit SHK-Defaults; Activity-Stream läuft; Task↔CRM-Links verdrahtet (Retro-Integration aus P4).

Milestone Inhalt
M042 kontakt-stammdaten Contact als First-Class-Tabelle (AD-2: kein Entity-Builder!), Listen/Detail, Inline-Edit
M043 firma-stammdaten Company + M:N zu Kontakten mit Rollen + Primär-Markierung
M044 schlagwoerter-custom-felder Tags (farbig, entity-übergreifend) + CustomFieldDefinition/Value je Tenant + SHK-Template-Seeds
M045 aktivitaets-stream Append-only Activity-Tabelle (Event-Sourcing), chronologische Stream-View, logActivity() überall
M046 listen-segmente-dsgvo Server-seitige Filter/Sortierung/Pagination, Bulk-Actions, CSV-Export, Duplikat-Merge-Tool

AP-5: P7 Lead-Inbox (Do/Fr 25./26.06.)

Was: Der Eingangs-Trichter. Jede Anfrage (Formular, Inbound-Mail, Anruf, Fremd-Website via Quellen-Token) landet hier. Fertig heißt: Lead kommt aus mind. 2 Quellen automatisch rein, Spam wird markiert, Promotion-Modal erzeugt Kontakt (+optional Deal-Event für P8). Extension-Point: lead.qualified-Event.

Milestone Inhalt
M047 quellen-adapter Multi-Quellen-Framework: Form, Inbound-Mail-Adresse, Webhook-URL mit Token je Quelle
M048 routing-pro-quelle Auto-Zuweisung je Quelle (wer bekommt Website-Leads?)
M050 spam-duplikat-erkennung Spam-Score mit Begründung, Honeypot, Limits je IP/Quelle, Duplikat-Hinweise
M051 status-pipeline-gruende Lead-Status (new/qualified/converted/lost/spam) + Verlust-Gründe (Range-Hinweis: braucht nur M047/M048/M050)

Außerdem Do 25.: [€] Partner-Gespräch Preise. Fr 26.: Noah-Demo 1 + Lagerist-Frage + Payment-Link an Haris.

AP-6: P8 Sales-Pipeline (Sa bis Mo 27. bis 29.06.)

Was: Deals im Kanban bis zum Won-Handoff ans Projekt. Fertig heißt: Lead-Qualifizierung erzeugt Deal (M049, Retro aus P7) · Kanban mit Drag&Drop · Won → Projekt-Anlage-Option · deal.won-Event + Aggregat-APIs (Extension-Points für P9/P11). SHK-Pipelines + Gründe selbst seeden (AD-12).

Milestone Inhalt
M049 auto-verkaufsfall Bei Lead-Status qualified: Deal automatisch anlegen (konsumiert P7-Event)
M059 pipeline-konfiguration Multi-Pipeline + Stage-Editor (Art offen/won/lost, Win-%, Farbe) + SHK-Seed
M060 verkaufsfall-crud Deal-Entity mit Nummer, Volumen (permission-gegated!), Custom-Feldern, Stage-Historie
M061 kanban-ui Kanban-Board (Davids Screen): Drag&Drop, Aggregate je Spalte, Stuck-Marker
M062 verlust-gewinn-gruende Lost-Reason-Pflicht bei Lost-Drop, Gründe-Verwaltung + Seed
M063 auto-auftragsprojekt Won-Handoff: Deal → Projekt mit Übernahme (Setter/Closer-Logik); liefert deal.won-Event
M064 pipeline-reporting Basis-KPIs + Aggregat-APIs (Forecast einfach: Volumen × Win-%); KWP-Sync-Anteil ruht bis v2

Mo 29.: v2-Vorlauf-Externals (30 min, siehe Externals-Tabelle).

AP-7: P9 Projekte & Plantafel (Di bis Do 30.06. bis 02.07.)

Was: Auftragsabwicklung + das Monteur-Herzstück. Plantafel + Abnahme sind mobile-first und offline (PWA-only statt nativer App, AD-17 — gilt für v1 und v2). Fertig heißt (= Gate W3 am Fr): Kette Lead → Deal → Projekt E2E klickbar · Plantafel mit Konflikt-Anzeige (inkl. HR-Abwesenheiten) · Abnahme offline mit Unterschrift + PDF. OfflineSyncQueue als pures TS mit Storage-Interface (PWA-ready!).

Milestone Inhalt
M065 auftragspipeline-konfiguration Projekt-Pipelines analog Sales + SHK-Seed + Abnahme-Pflicht-Flag je Stage
M066 auftrag-crud Projekt-Entity, Mitglieder mit Rollen (PL!), Sales-Verlauf-Tab; KWP-Archiv-Anteil ruht (Extension-Point)
M067 plantafel Scheduling-Board MA × Zeit, Drag&Drop, Konflikte (Doppelbelegung/Urlaub); VM-Slots für Termine/Abwesenheiten
M068 mitglieder-mgmt Mitglieder-Verwaltung + Benachrichtigungen über notify()
M069 abnahme-workflow SHK-Abnahme-Formular (fix in v1) → Mängel-Klassifizierung → Touch-Unterschriften → PDF + Auto-Mail, offline
M070 material-listen Material-Liste am Auftrag (Position/Menge/Status); Lagerist-Sicht ruht bis v2 (Noah-Antwort abwarten)

AP-8: P11 Suche & Dashboard (Sa/So 04./05.07.)

Was: Alles wiederfinden + Kennzahlen sehen. Retro-Integrationen einplanen: Suche in Audit-Viewer/Datei-Browser/CRM-Segmente/Kanban-Filter nachrüsten, Sales-Widgets aus P8-Aggregaten, Dashboard-Defaults selbst seeden. Fertig heißt: Cmd+K findet jede Entität permission-aware (Meilisearch, scoped Key auf node1) · 3 feste Rollen-Dashboards (GF/Büro/Monteur) live via SSE.

Milestone Inhalt
M056 such-index SearchIndexEntry + Outbox-Pattern: jede Mutation aktualisiert den Index (Registry aus P1)
M057 permission-aware-search Treffer respektieren Permissions server-seitig (kein Leak über Suche!)
M058 such-ui Cmd+K-Modal (300ms debounce, Gruppierung, Highlight) + Vollbild-Suche mit Filtern
M147 layout-widget-engine Widget-Registry + 3 feste Rollen-Layouts (kein Drag&Drop; Registry bleibt voll für Inversionen)
M148 standard-widgets Die Standard-Widgets: Sales-KPIs, Projekt-KPIs, meine Tasks, Termine heute, Auslastung, Mängel

AP-9: P12 Automation-Engine, USP-Säule 1 (Mo bis Mi 06. bis 08.07.)

Was: Der visuelle Flow-Editor über alle Module. VOLL, ohne Dünnung (deine Ansage: „dringend"). Fertig heißt: Flow aus Trigger + Bedingungen + Aktionen läuft produktiv · Dry-Run zeigt Klartext-Vorschau · 24h-Undo funktioniert · Loop-Guard erkennt Schleifen · jede Execution hat deutsche Step-Logs.

Milestone Inhalt
M075 schema-ausloeser Trigger-Library: CRM/Sales/Projekte/Email/Forms/Kalender/Zeit/Webhooks (Events aus allen v1-Modulen)
M076 aktion-registry Action-Library typsicher erweiterbar (KI-Actions docken in P13 an, KWP-Push in v2)
M077 bedingungen If/Else, Filter-Bedingungen auf Entity-Feldern, UND/ODER-Gruppen
M078 visueller-editor Graph-Canvas (Davids Screen): Knoten-Katalog, Konfig-Panel, Mini-Map, Undo/Redo
M079 test-lauf-vorschau Dry-Run: „trifft X Datensätze, würde an [Liste] senden" + Bestätigungs-Pflicht
M080 undo-fenster 24h-Reverse: ausgeführte Automation rückgängig machen (kompensierende Aktionen)
M081 schleifen-webhook-anomalie Loop-Guard (A→B→A erkannt → Modal mit Graph), Webhook-Sturm-Schutz, Anomalie-Pause
M082 klartext-logs-metering Deutsche Step-by-Step-Logs je Execution + Verbrauchs-Zähler (Quota-Basis)

AP-10: P13 KI-Layer, USP-Säule 2 (Do 09.07., dann FREEZE)

Was: EU-LLM-Unterbau + Sprach-zu-Automation (exklusiv im Flow-Editor, KEIN HiveMind-Koppeln!). Fertig heißt: „Wenn ein Lead 3 Tage offen ist, erinnere den Verantwortlichen" als gesprochener/getippter Satz erzeugt einen Flow-Entwurf, der NIE ohne User-OK aktiv wird · Promptfoo-Suite grün · Limits + Drossel greifen.

Milestone Inhalt
M083 eu-provider-layer LLM-Gateway: Mistral La Plateforme (EU), RetrievalProvider-Interface als HiveMind-Andockpunkt
M084 multi-provider-fallback Provider-Abstraktion mit Fallback-Kette (zweiter EU-Provider folgt v2)
M085 promptfoo-eval-suite Eval-Suite gegen Prompt-Regressionen (CI-Gate für KI-Änderungen)
M086 sprach-zu-automation NL → Flow-Entwurf mit direkten DB-Prüfungen (kein RAG), Rückfragen bei Mehrdeutigkeit, Bestätigungs-Grenze
M088 token-limits Lokales AiCredits-Konto, Soft-Limit-Banner 80 %, Hard-Limit + Drossel (Kauf kommt aus P20)

v2-Pakete (13. bis 31.07.)

AP-11: KWP-Recut + Public-API + API-Keys (Mo 13. bis Fr 17.07.)

Fertig heißt: M089 bis M095 sind gegen die echte API-Doku neu geschnitten (kwpsync.exe ist tot) · Read-REST-API läuft mit Key-Auth gegen Staging.

Milestone Inhalt
M161 api-spec-read Read-Only-REST für Contacts/Deals/Leads/Projects/Tasks/Companies + OpenAPI-Spec auto-generiert
M162 key-auth-rate-limit API-Key-Auth + Rate-Limit + Scopes
M163 webhooks Eingehende Lead-Webhooks + ausgehende HMAC-signierte Subscriptions mit Retry
M027 api-keys-ui Tenant-Settings: Keys erstellen/widerrufen, Scopes, SHA-256-Speicherung (Boilerplate-Modell aktivieren)

AP-12: HiveMind/RAG + Whisper + pgvector (Sa/So 18./19.07. Start, fertig parallel zu KWP)

Milestone Inhalt
M087 hivemind-rag KI-Assistent mit Retrieval über RetrievalProvider (Adapter liegt seit v1); pgvector-Spalte + Hybrid-RRF rüsten Suche nach (AD-5 Teil 2); Whisper-Diktat (Notiz/Abnahme); Bestätigungs-Grenze geerbt aus M086

AP-13: KWP-Integration, der USP (Mo 20. bis So 26.07.)

Fertig heißt: Fr 24.07. Sync-E2E mit Geerkens-Testdaten · „KWP gewinnt"-Konfliktregel beweisbar · Drift-Sentinel meldet Schema-Änderungen.

Milestone Inhalt (Recut-Stand)
M089 (recut) KWP als DataConnection type='rest-api' über die Apps-Engine, OAuth/PKCE (Callback-URL ist registriert)
M090 heartbeat-recovery Verbindungs-Überwachung + Auto-Recovery (vereinfacht durch API)
M091 warteschlange-replay Sync-Queue mit Replay bei Fehlern (Idempotenz aus M007)
M092 schema-drift-sentinel API-Versions-/Schema-Snapshot + Drift-Erkennung + Admin-Notification
M093 konflikt-aufloesung Bidirektionaler Sync mit Regel „KWP gewinnt" (AD-14)
M094 plantafel-sync KWP-Termine ↔ Plantafel (Retro-Integration in P9-Slots)
M095 dokumenten-archiv-sync Auftrags-Dokumente ↔ KWP-Archiv (Retro in M066/M070-Extension-Points)
M074 aufgaben-sync-erp Task-Sync mit KWP (Teil des Recut-Scopes)

AP-14: AdminUser-Welt (Mo 27. bis Mi 29.07.)

Milestone Inhalt
M038 admin-mitarbeiter Getrennte AdminUser-Identität (eigene Credentials/Sessions, 8h-Cap, IP-Bindung); löst v1-Auflagen-Brücke ab
M039 admin-konten-rollen AdminRBAC (super_admin/support/sales/engineering)

AP-15: HalloPetra + DSGVO-Auskunft (Mi 29. bis Fr 31.07.)

Milestone Inhalt
M105 hallopetra Zweiter Telefonie-Adapter (KI-Telefonist) über das TelephonyProviderInterface aus P15
M166 dsgvo-auskunft Auskunfts-Tooling (Art. 15): Betroffenen-Suche → Report; ersetzt das manuelle v1-Playbook

Quellen für Tiefe: docs/milestones/M0xx-*/PLAN.md je Milestone · SCREEN-MAP.md (UI-Inhalte) · PHASE-SOURCES.md (Retro-Integrations-Register: beim Planen jeder Phase MIT einplanen!) · TIMELINE.md (Gesamtbild). Bei Phasen-Start: /gsd-plan-phase N lesen lassen.