Files
HiveGrid-Wireframes/hivegrid-cloud/.planning/REQUIREMENTS.md
T

409 lines
35 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.
# Requirements: HiveGrid 2.0
**Defined:** 2026-06-07
**Core Value:** Jeder SHK-Betrieb (Mandant) wickelt die komplette Wertschöpfungskette — Lead → Projekt (frei konfigurierbare Pipelines) (→ KWP-Sync ab v2) — inklusive visueller KI-Automation in einem einzigen, DSGVO-konformen EU-System ab. Wenn diese Kette nicht durchgängig funktioniert, scheitert das Produkt. *(Scope-Schnitt #12, 12.06.: KWP = erstes v2-Modul — API-Zugang des Herstellers erst ~19.07., nach v1-Launch.)*
> ✅ **MODELL-PIVOT 2026-06-13 (AD-20) — Module 1–4 nachgezogen (R-REFIT, 16.06.):** Projekt-zentrisch (ein `Projekt`-Kern, Pipelines = Views). Umgesetzt: **REQ-crm-lead-promotion entfällt → REQ-lead-projekt-konvertierung** (Lead → Projekt bei Weiterverarbeitungsfreigabe, kein Modal, E4); **Sales (Modul 3) + Projekt (Modul 4) konsolidiert** zu „Projekt & Pipelines" mit Pipeline-Feld-Config-/Rechte-Layer (PipelineAccess/-FieldConfig/-FieldVisibility); **REQ-rechnung-sub-entity (NEU, E3)** angelegt; Kontaktmodell (Kontakttyp Privatperson/Organisation, -status, -art als Relation); Abnahme bleibt v1 als Checklisten/Protokoll-Sub-Area (E2). Single Source: `.planning/ENTITY-MODEL.md`.
## v1 Requirements
### Modul 1 — CRM-Kern
- [ ] **REQ-crm-datenmodell**: Typisierte First-Class-Prisma-Tabellen für alle CRM-Kernentitäten (Kontakt als Oberbegriff mit Kontakttyp Privatperson/Organisation, KontaktRelation, Lead, Activity, CustomField, Tag) mit RLS-Policies auf allen Tabellen.
- [ ] **REQ-crm-listen-views**: Kontakt- und Organisations-Listen mit server-seitiger Filter-, Sortier- und Paginierungslogik, Bulk-Actions und CSV-Export.
- [ ] **REQ-crm-detail-views**: Kontakt-, Organisations- und Lead-Detailansichten mit Inline-Edit, Activity-Stream, verknüpften Entitäten und Custom-Feldern.
- [ ] **REQ-lead-projekt-konvertierung**: Lead → Projekt bei `Weiterverarbeitungsfreigabe` (ja/nein/unklar); relevante Lead-Daten werden ins Projekt vererbt, der Kontakt wird separat verknüpft (kein Promotions-Modal, AD-20). *(Pivot 13.06.: ersetzt das frühere REQ-crm-lead-promotion / 4-Optionen-Modal.)*
- [ ] **REQ-crm-activity-stream**: Zentrale append-only Activity-Tabelle (Event-Sourcing) als chronologische Stream-View pro Entität, filterbar nach Typ/Actor/Zeitraum.
- [ ] **REQ-crm-custom-felder**: CustomFieldDefinition + CustomFieldValue pro Tenant für Kontakt/Lead/Projekt/Rechnung, mit Admin-Verwaltungs-Route, pro Pipeline via PipelineFieldConfig schaltbar und SHK-Branchen-Template-Defaults.
- [ ] **REQ-crm-duplikat-erkennung**: Live-Match-Check beim Anlegen und Bulk-Duplikat-Tool für Admins mit Side-by-Side-Merge.
- [ ] **REQ-crm-tags**: Tag-System mit ad-hoc-Erstellung, Farbgebung, Entity-übergreifender Verwaltung und Listen-Filter-Integration.
- [ ] **REQ-crm-permissions**: Permission-Bundle crm.* (read_own, read_all, write, delete, admin) mit Owner-Check und server-seitigem Permission-Filter.
### Modul 2 — Lead-Inbox
- [ ] **REQ-lead-inbox-liste**: Lead-Inbox als Arbeitsplatz mit Status-Filter, Triage-Quick-Actions, Bulk-Operationen und Real-time-Refresh.
- [ ] **REQ-lead-quellen-auto-anlage**: Automatische Lead-Anlage aus Form-Submission, eingehender E-Mail und AirCall-Inbound-Anruf mit Automation-Trigger.
- [ ] **REQ-lead-status-workflow**: Status-Enum (new|qualified|converted|lost|spam) mit definierten Übergängen und DSGVO-Auto-Lösch-Cron.
- [ ] **REQ-lead-anti-spam**: Rate-Limiting und Anomalie-Detection für Lead-Quellen mit Quarantäne-Modus und Tenant-Admin-Notification.
- [ ] **REQ-lead-statistiken**: Statistiken-Page mit KPI-Kacheln, Quellen-Aufschlüsselung und Trend-Charts, Permission-aware.
- [ ] **REQ-lead-permissions**: Permission-Bundle leads.* mit Owner-Check-Logik und permission-awarern Server-side-Filtern in allen Listen.
### Modul 3 — Projekt & Pipelines (Teil 1: Kern + Pipeline-Engine)
> *(Pivot 13.06., AD-20: ein `Projekt`-Kern; „Deal"/„Auftrag" = Pipeline-Typen (typ_hint), keine eigenen Entitäten. Single Source: ENTITY-MODEL.md.)*
- [ ] **REQ-projekt-kern-datenmodell**: Ein typisierter `Projekt`-Kern (Superset-Tabelle, Deal- + Auftrags-Felder) mit RLS und HiveNumberSeq für fortlaufende Projekt-Nummern; Pipeline (typ_hint sales/auftrag/custom) + PipelineStage (= Status, pipeline-intern; stage_kind offen/gewonnen/verloren) als konfigurierbare Views.
- [ ] **REQ-pipeline-rechte-config**: Pipeline-Feld-Config- und Rechte-Layer schon v1 komplex — PipelineAccess (wer sieht/bearbeitet Pipeline) + PipelineFieldConfig (Feld sichtbar/pflicht je Pipeline+Status) + PipelineFieldVisibility (Field-Level-Rechte je Rolle/Gruppe/User, z.B. Auftragsvolumen nur für Vertrieb).
- [ ] **REQ-projekt-kanban-listen-view**: Ein konfigurierbarer Kanban-View (Drag-&-Drop, Stage-Wechsel) und Listen-View mit Filter, Bulk-Actions, Real-Time-Updates und Reverse-Window für gewonnen/verloren.
- [ ] **REQ-projekt-pipeline-wechsel**: Projekt-Anlage aus mehreren Quellen, Stage-Wechsel-Validation und Pipeline-Wechsel statt Won-Handoff (ein Projekt wechselt nur die Pipeline — kein zweiter Datensatz entsteht); Auto-Archive-Cron für abgeschlossene Projekte.
- [ ] **REQ-projekt-forecast-kpis**: Forecast-Berechnung, KPIs pro Vertriebler, Stage-Conversion-Rates und Verlust-Grund-Auswertung mit Aggregat-Cache.
### Modul 4 — Projekt & Pipelines (Teil 2: Auftrags-Features + Sub-Areas)
> *(Pivot 13.06., AD-20: Auftrags-Welt = Pipeline-View auf denselben `Projekt`-Kern. Material/Zeiterfassung/Leistungspositionen/Baustelle/Support → v2.)*
- [ ] **REQ-projekt-sub-areas**: Sub-Areas am Projekt-Kern (Termine, Aufgaben, Aktivitäten, Dokumente, Checklisten, ProjektMitglied/Monteur-Zuweisung) + Plantafel-Ansicht für Ressourcen-Scheduling pro Monteur/Tag, offline-fähig.
- [ ] **REQ-rechnung-sub-entity**: `Rechnung` als einfaches Sub-Entity am Projekt-Kern (Liste/Anlegen/Verknüpfen) mit fortlaufender Rechnungsnummer (HiveNumberSeq, lückenlos/GoBD), Status (entwurf/gestellt/bezahlt/storniert) und PDF-Anhang. *(Pivot 13.06., E3 — einziger echter v1-Scope-Zuwachs.)*
- [ ] **REQ-projekt-abnahme**: AbnahmeProtokoll (+ AbnahmeSignatur) als immutable Sub-Area direkt am Projekt mit Touch-Unterschrift, Offline-Sync und M05-Form-Template-Unterstützung; „Mängel" als Checkliste (typ=maengel).
### Modul 5 — Form Builder
- [ ] **REQ-form-datenmodell**: Form, FormField, FormSubmission und FormAction als Datenmodell mit 12 Feld-Typen und konfigurierbaren Post-Submit-Aktionen. *(Scope-Schnitt 12.06.: FormLink — personalisierte Links mit Tracking/Ablauf/Limit — + JS-Snippet → v2; öffentliche URL, QR-Code und iFrame-Embed bleiben.)*
- [ ] **REQ-form-editor**: Drag-&-Drop-Form-Editor mit Echtzeit-Vorschau, Conditional Logic, SHK-Form-Templates und iFrame-Embed-Code.
- [ ] **REQ-form-actions**: Form-Actions nach Submission (Lead/Deal/Task anlegen, Webhook, Email, Automation-Trigger) mit Field-Mapping und ActionLog.
### Modul 6 — Booking
- [ ] **REQ-booking-datenmodell**: BookingPage, AvailabilityRule, AvailabilityException und Appointment als Datenmodell für öffentlich erreichbare Buchungsseiten.
- [ ] **REQ-booking-slot-kalkulierung**: Slot-Berechnung unter Berücksichtigung von Verfügbarkeitsregeln, Ausnahmen, Kalender-Sync (M25) und Puffer, Timezone-aware.
- [ ] **REQ-booking-integrationen**: Lead-Inbox-Integration, Activity-Eintrag, Bestätigungs-Email und iFrame-Embed-Code nach Terminbuchung.
### Modul 7 — Angebot + Signatur
- [ ] **REQ-signatur-datenmodell**: DealSignatureDocument, DealSignatureSigner und SignatureProviderConnection für Multi-Signer-Workflows mit PandaDoc/DocuSign.
- [ ] **REQ-signatur-provider**: PandaDoc/DocuSign-Integration via Apps-Engine (M33a) mit OAuth-Connect-Flow, Webhook-Verarbeitung und Status-Updates.
### Modul 9 — Email-Inbox
- [ ] **REQ-email-datenmodell**: EmailIntegrationMailbox, EmailIntegrationMessage, TenantSendingDomain und TenantInboundAddress für bidirektionalen Gmail/Outlook-Sync.
- *(→ v2, Scope-Schnitt 2026-06-11)* **REQ-email-sync-strategie**: Bidirektionaler Sync Gmail/Outlook über ProviderAdapter-Interface mit Auto-Matching von Absendern zu Contact/Lead.
- *(→ v2, Scope-Schnitt 2026-06-11)* **REQ-email-inbox-view**: Inbox-View, Thread-View und Compose mit Permission-Scoping und CRM-Kontext-Verknüpfung.
### Modul 10 — Email-Marketing
- [ ] **REQ-marketing-datenmodell**: Campaign, OutboundEmail, EmailTemplate, RecipientSegment und EmailSuppressionList als Datenmodell mit DSGVO-konformem Tracking.
- [ ] **REQ-marketing-double-optin**: Double-Opt-In-Workflow mit DSGVO-Compliance, One-Click-Unsubscribe und Suppression-List-Check vor jedem Versand.
- [ ] **REQ-marketing-versand**: BullMQ-basierter Versand mit Rate-Limiting, Bounce-Handling und SMTP-Provider-Abstraktion (Mailjet, AD-6 gelockt).
### Modul 12 — Telefonie (AirCall)
- [ ] **REQ-telefonie-datenmodell**: TelephonyConnection, TelephonyUserBinding und TelephonyCallSession als Datenmodell für AirCall-Integration mit verschlüsselten OAuth-Tokens.
- [ ] **REQ-telefonie-provider-adapter**: TelephonyProviderInterface mit AirCallAdapter für Click-to-Call, Inbound-Webhook-Verarbeitung und automatische Lead-Anlage bei unbekannter Nummer.
### Modul 13 — Team-Chat
- [ ] **REQ-chat-datenmodell**: TeamChat, TeamChatMessage, Threads, Reactions und TeamChatRead als Datenmodell für drei Channel-Typen (public, private, entity-linked).
- [ ] **REQ-chat-realtime**: WebSocket-basiertes Real-Time-Messaging mit Presence, Typing-Indicator, Read-Receipts und Redis-Pub/Sub für Scale-Out.
- [ ] **REQ-chat-features**: Link-Previews, File-Uploads, @Mentions, Chat-Verlaufs-Suche und Entity-linked Channels im Deal/Projekt-Detail.
### Modul 14 — HR-Hub
- [ ] **REQ-hr-datenmodell**: HrEmployeeProfile, EmployeeVacationRequest, EmployeeSickLeaveReport, EmployeePayslip und HrRequest als Datenmodell mit AES-256-GCM-Verschlüsselung für sensible Daten.
- [ ] **REQ-hr-passwort-safe**: Verschlüsselter Passwort-Safe pro Mitarbeiter mit KMS-backed Envelope-Encryption, Audit-Trail und DSGVO-Export.
- [ ] **REQ-hr-urlaub-krank**: Urlaubs-Anfrage-Workflow (mehrstufiger Approval) und Krankmeldungs-Erfassung mit Abwesenheits-Kalender-Integration.
### Modul 15 — Customer-Portal
- *(→ v2, Scope-Schnitt 2026-06-11)* **REQ-portal-datenmodell**: PortalUser, CustomerPortalSession, CustomerPortalProjectAccess und PortalConfiguration als vollständig getrennte Portal-Datenwelt.
- *(→ v2, Scope-Schnitt 2026-06-11)* **REQ-portal-auth-magic-link**: Magic-Link-Authentication für Endkunden (getrennte Auth-Welt, AD-3) mit One-Time-Token, IP-Bindung und DSGVO-Lösch-Workflow.
- *(→ v2, Scope-Schnitt 2026-06-11)* **REQ-portal-projekt-sicht**: Projekt-Sicht für Endkunden (nur explizit freigegebene Projekte), Dokument-Upload und Portal-Forms, Default-Sichtbarkeit NICHT sichtbar.
### Modul 17 — Automation Engine
- [ ] **REQ-automation-datenmodell**: AutomationRule (JSON-Graph), AutomationExecution, AutomationStepExecution und AutomationTemplate als Datenmodell für den Flow-Editor.
- [ ] **REQ-automation-trigger-library**: Phase-1-Trigger-Library über alle Module (CRM, Sales, Projekte, Email, Forms, Kalender, Zeit-Trigger, Webhooks).
- [ ] **REQ-automation-action-library**: Phase-1-Action-Library über alle Module (CRM-Aktionen, Notifications, KWP-Push, HTTP-Request, Tasks, If/Else, Delay, Loop).
- [ ] **REQ-automation-flow-editor**: Graph-basierter visueller Flow-Editor mit KI-Erstellung per natürlicher Sprache (DE), Dry-Run und 24h-Undo.
- [ ] **REQ-automation-schutz**: Loop-Guard, Rate-Limit, Idempotenz-Key, Resume-Mode und Trigger-Volumen-Metering pro Tenant.
### Modul 18 — ~~KI-Layer~~ → MCP-Server ([[AD-26]])
> ⛔ **KI→MCP-Pivot ([[AD-26]]):** HiveGrid hostet kein eigenes LLM/RAG/Whisper mehr, sondern wird Remote-MCP-Server. Die vier KI-Requirements unten sind **entfernt bzw. zurückgestellt**; an ihre Stelle tritt `REQ-mcp-server` (siehe unten). Verbindliche Bau-Spec: [[VR-MCP]]/[[VD-MCP]].
- [ ] **REQ-mcp-server**: Remote-MCP-Server (Streamable HTTP, `@modelcontextprotocol/sdk`), der HiveGrid-Daten als **Read-Ressourcen** und freigegebene Schreib-Operationen als **Action-Tools** für externe KI-Clients bereitstellt. **Auth = API-Key + Scopes + Rate-Limit aus der Public-API** ([[VR-P22]]); Tenant wird aus dem Token abgeleitet, jeder Zugriff läuft durch `withTenantScope()`/RLS. Jede Action ist `withPermission()`-gegated, erzwingt bei Schreib-Operationen eine **Confirmation** und wird via M001-Audit protokolliert (Actor-Kind „MCP/Agent"). Keine neuen KI-Entitäten — Nutzung von `ApiKey`/`Credential` (ggf. kleine `McpGrant`/Scope-Tabelle).
- ~~**REQ-ki-llm-gateway**: EU-only LLM-Gateway (Mistral La Plateforme primär; …) mit Token-Tracking und Pay-as-you-go-AI-Credits.~~ → **entfernt (KI→MCP, [[AD-26]])** — kein eigenes LLM-Gateway.
- ~~**REQ-ki-rag-embeddings**: RAG-Pipeline mit pgvector, Outbox-Pattern für Embedding-Jobs und RLS-gefiltertem Top-K-Retrieval.~~ → **zurückgestellt (KI→MCP, [[AD-26]]; v3-Kandidat)**.
- ~~**REQ-ki-whisper**: Whisper-Transkription für Anruf-Aufzeichnungen über EU-Endpoint mit Token-Tracking und AiCredits-Deduktion.~~ → **zurückgestellt (KI→MCP, [[AD-26]]; v3-Kandidat)**.
- ~~**REQ-ki-hivemind**: HiveMind-KI-Assistent mit kontextuellem RAG-Chat, Conversation-History und Promptfoo-basiertem Sicherheits-Testing.~~ → **zurückgestellt (KI→MCP, [[AD-26]]; v3-Kandidat)**.
### Modul 19 — KWP-Integration
- *(→ v2, Scope-Schnitt 2026-06-12 — erstes v2-Modul)* **REQ-kwp-datenmodell**: KwpSettings, KwpRegistry, KwpProjectQueue, KwpApiKey und KwpSchemaSnapshot als Cloud-seitiges Datenmodell (keine KWP-DB-Credentials in Cloud).
- *(→ v2, Scope-Schnitt 2026-06-12 — erstes v2-Modul; ⚠ Recut: offizielle REST-API statt kwpsync.exe)* **REQ-kwp-architektur**: ~~Drei-Komponenten-Architektur (HiveGrid Cloud, kwpsync.exe Windows-Client, KWP MSSQL-DB)~~ → KWP als `DataConnection type='rest-api'` mit bidirektionalem Sync und Adapter-Pattern.
- *(→ v2, Scope-Schnitt 2026-06-12 — erstes v2-Modul)* **REQ-kwp-schema-drift**: Schema-Drift-Sentinel für Schema-/API-Versions-Änderungen mit regelmäßigem Snapshot, Drift-Detection und Tenant-Admin-Notification.
### Modul 20 — Dashboard
- [ ] **REQ-dashboard-datenmodell**: Dashboard, DashboardLayout und WidgetInstance als Datenmodell mit Role-Default-Layouts (SHK-Template geseedet). *(Scope-Schnitt 12.06.: 3 feste Rollen-Layouts GF/Büro/Monteur; Drag&Drop + User-Layout-Persistenz → v2.)*
- [ ] **REQ-dashboard-widgets**: Widget-Katalog mit Datenquellen aus Sales, Projekte, Tasks, HR und KI; Realtime-Updates via WebSocket/SSE und Aggregat-Cache.
### Modul 21 — Audit-Log
- [ ] **REQ-audit-datenmodell**: Append-only AuditEntry mit SHA-256-Hash-Kette (Tamper-Nachweisbarkeit) und automatischer Generierung über Prisma-Middleware.
- [ ] **REQ-audit-retention-export**: Fixe Default-Retention (10 Jahre), BullMQ-Export-Jobs als NDJSON/CSV in S3-kompatibles Object Storage (Hetzner) und Cron-Auto-Löschung. *(Scope-Schnitt 12.06.: tenant-konfigurierbare Retention-Policy, Legal-Hold, Saved-Views → v2; Boilerplate liefert Retention-Cron + PDF-Export.)*
- [ ] **REQ-audit-permissions**: Audit-Zugriff permission-gegated (audit.read, audit.export) mit Plattform-Admin-View für mandantenübergreifende Einträge.
### Modul 22 — Notifications
- [ ] **REQ-notification-datenmodell**: Notification, NotificationPreference und NotificationDevice als Datenmodell. *(Scope-Schnitt 12.06.: NotificationBundle + NotificationQuietHours → v2 mit M117.)*
- [ ] **REQ-notification-versand-pipeline**: Drei-Kanal-Versand (In-App via SSE, Email, Web-Push via VAPID) über BullMQ mit notify()-Pflicht-Interface aus @hivegrid/notifications. *(Scope-Schnitt 12.06.: Sofort-Zustellung ohne Bündelung/Quiet-Hours; Push-Kanal Stub bis v2.)*
### Modul 23 — Files
- [ ] **REQ-files-datenmodell**: File, FileChunk, FileUploadProgress und FileEntityLink als Datenmodell mit S3-kompatiblem Object-Storage-Backend (Hetzner, Infra-ADR-009) und RLS auf Storage-Pfaden. *(Scope-Schnitt 12.06.: FileVersion → v2.)*
- [ ] **REQ-files-upload-preview**: Chunked-Upload (TUS), Preview-Generierung (PDF→PNG, Bild→WebP, **HEIC→JPG** — Pflicht für iPhone-Monteur-Fotos) und Customer-Portal-Upload-Unterstützung. *(Scope-Schnitt 12.06.: Versionierung, Office-/Video-Previews, Resume-Upload, OCR → v2.)*
### Modul 24 — Globale Suche
- [ ] **REQ-suche-datenmodell**: SearchIndexEntry, RecentSearch und Outbox-Pattern für Index-Jobs nach Entity-Mutationen. *(Scope-Schnitt 11.06., AD-5 sequenziert: pgvector-Embedding-Spalte → v2 mit HiveMind; Outbox-Events sind der v1-Andock-Adapter.)* **⚠️ KI→MCP-Pivot ([[AD-26]]): Die KI/Embedding-Hälfte ruht — RAG/pgvector entfällt; das `embedding`-Feld bleibt ungenutzt. Meilisearch-Keyword-Suche bleibt unverändert.**
- [ ] **REQ-suche-hybrid**: Keyword-Suche via Meilisearch mit permission-awarem SearchAdapter-Interface (INTEGRATION-CONTRACTS §8). *(Scope-Schnitt 11.06., AD-5 sequenziert: pgvector/Hybrid-RRF-Fusion → v2 mit HiveMind.)* **⚠️ KI→MCP-Pivot ([[AD-26]]): pgvector/Hybrid-RRF-Fusion ruht (RAG entfällt); v1+v2 = reine Meilisearch-Keyword-Suche.**
- [ ] **REQ-suche-ui**: Cmd+K-Modal (global Hotkey, debounced) und Vollbild-Such-View mit persistierter Suche und RecentSearch-Anzeige.
### Modul 25 — Calendar-Sync
- [ ] **REQ-kalender-datenmodell**: CalendarConnection, CalendarEvent, CalendarEventMapping und CalendarSyncCursor für bidirektionalen Google/Outlook-Sync mit verschlüsselten OAuth-Tokens.
- [ ] **REQ-kalender-sync-adapter**: CalendarAdapter-Interface (GoogleCalendarAdapter + OutlookAdapter) mit Auto-Token-Refresh, Webhook-Subscriptions und bidirektionaler HiveGrid-Terminanlage.
### Modul 26 — Tasks
- [ ] **REQ-tasks-datenmodell**: Task mit Status, Priorität, Fälligkeit, Entitäts-Verknüpfung (Contact/Company/Lead/Deal/Project) und TaskWatcher.
- [ ] **REQ-tasks-reminder-archivierung**: Reminder-System via M22 (konfigurierbare Vorlaufzeit) und Auto-Archivierung abgeschlossener Tasks nach 30 Tagen per Cron.
### Modul 27 — Auth / Multi-Tenancy / Permissions
- [ ] **REQ-auth-multi-tenancy**: Self-Service-Signup mit auto-generiertem Tenant-Slug, Reserved-Words-Validierung und URL-Struktur (app.hivegrid.de, admin.hivegrid.de).
- [ ] **REQ-auth-methoden**: Email+Passwort (NIST-konform, Breach-Check), TOTP-2FA (RFC 6238) und Magic-Link exklusiv für Customer-Portal (AD-3).
- [ ] **REQ-auth-rbac**: Rollen-basiertes Permission-System (Role ↔ User M:N) mit Permission-Keys in packages/entitlements und 6 SHK-Standard-Rollen geseedet.
- [ ] **REQ-auth-user-lifecycle**: User-Einladung (48h-Token), Soft-Deactivation und DSGVO-Löschung via PII-Anonymisierung ohne Audit-Trail-Verlust.
- *(→ v2, Scope-Schnitt 2026-06-12)* **REQ-auth-api-keys**: API-Key-System mit SHA-256-Hash-Speicherung, fein-granularen Scopes und Rate-Limit (1000 Req/Min Default). *(Wandert mit der Public-API; Boilerplate-`ApiKey`-Modell bleibt ungenutzt im Code.)*
### Modul 28 — Subscriptions/Billing
- [ ] **REQ-billing-datenmodell**: TenantSubscription mit Stripe-Integration, Frozen-Modus (Read-Only-Middleware), AI-Credits-Konto und Stripe-Webhook-Verarbeitung.
- [ ] **REQ-billing-trial-dunning**: 14-Tage-Trial ohne Kreditkarte, Dunning-Email-Sequenz (Tag 1/3/7) bei fehlgeschlagener Zahlung und anschließender Frozen-Modus.
### Modul 29 — Onboarding
- *(→ v2, Scope-Schnitt 2026-06-11)* **REQ-onboarding-wizard**: Branchen-getriebener Onboarding-Wizard nach Self-Service-Signup mit SHK-Template-Vorauswahl und OnboardingSession.
- [ ] **REQ-onboarding-demo-daten**: Demo-Daten-Provisioning auf Wunsch (5 Contacts, 3 Deals, 2 Projekte, Tasks) mit Lösch-Funktion via is_demo_data-Flag. *(Scope-Schnitt 12.06.: KI-Walkthrough → v2 mit Wizard-UI; Settings-Knopf statt Wizard-Schritt, einfaches Löschen.)*
### Modul 30 — i18n
- [ ] **REQ-i18n-architektur**: Locale-File-Struktur in packages/i18n, Language-Resolution (User → Tenant → DE), Build-Lint für Hard-Strings und ICU-Pluralisierung.
- [ ] **REQ-i18n-outbound**: Contact.language steuert Sprache der automatischen Outbound-Kommunikation; Notification-Templates in DE. *(Scope-Schnitt 12.06.: v1 DE-only — EN-Templates + Sprach-Wechsler → v2; i18n-Pflicht-Wiring + `verify:i18n`-Gate bleiben unantastbar, alles i18n-ready.)*
### Modul 31 — Branding
- [ ] **REQ-branding-theme-phase1**: User-Level Theme-Preference (Hell/Dunkel) mit SSR-kompatibler Cookie-Implementierung ohne Theme-Flash. *(Scope-Schnitt 12.06.: kein System-Modus — bewusst nur 2 Optionen; `next-themes` aus Boilerplate.)*
### Modul 32 — Feature-Flags
- [ ] **REQ-feature-flags-system**: Platform-Admin-Feature-Flag-System (FeatureFlag + TenantFeatureFlag) mit Redis-Cache, FeatureFlagFilter für automatische Aktivierung und AdminAuditLog.
### Modul 33a — Apps-Engine
- [ ] **REQ-apps-engine-datenmodell**: DataConnection, AppSyncRun, AppSyncItem und type-safe Adapter-Registry als zentrales Integrations-Framework.
- [ ] **REQ-apps-engine-lifecycle**: OAuth2-Connect-Flow (Gmail, Outlook, AirCall, PandaDoc), API-Key-Connect (KWP, Stripe), Connection-Health-Monitoring und Settings-UI.
### Modul 34 — Public API & Webhooks
- *(→ v2, Scope-Schnitt 2026-06-11)* **REQ-public-api-read**: Phase-1 Read-Only REST-API für Contacts, Deals, Leads, Projects, Tasks und Companies mit API-Key-Auth, Rate-Limit und Auto-genierter OpenAPI-Spec.
- *(→ v2, Scope-Schnitt 2026-06-11)* **REQ-public-webhooks**: Incoming Lead-Push Webhooks und ausgehende Webhook-Subscriptions mit HMAC-SHA256-Signatur, Retry-Logik und WebhookDelivery-Logging.
### Modul 35 — DSGVO-Export / Account-Löschung
- [ ] **REQ-dsgvo-export**: GDPR-Daten-Export als ZIP via BullMQ-Worker mit 72h-signed-Download-URL (S3-kompatibles Object Storage, Hetzner) und Download-Link-Email.
- [ ] **REQ-dsgvo-tenant-deletion**: Tenant-Account-Löschung mit Crypto-Shredding (Per-Tenant-DEK löschen), Stripe-Subscription-Cancel und vollständiger Storage/Cache-Bereinigung.
### Modul 36 — Mobile-PWA (PWA-only, kein nativer Client)
- *(→ v2, Scope-Schnitt 2026-06-11; PWA-only, AD-17)* **REQ-mobile-pwa**: Installierbare PWA (iOS Safari ≥ 16, Android Chrome ≥ 10) mit Service-Worker, Add-to-Homescreen, App-Manifest und Kamera-Upload über Web-APIs. *(Expo/Capacitor/native App verworfen — PWA-only, AD-17; nativer Client + App-Store → frühestens v3.)*
- *(→ v2, Scope-Schnitt 2026-06-11)* **REQ-mobile-offline-sync**: Voller Offline-Betrieb mit IndexedDB-lokalem Daten-Subset, OfflineSyncQueue, KWP-gewinnt-Konfliktauflösung und Offline-Indikatoren.
- *(→ v2, Scope-Schnitt 2026-06-11; PWA-only, AD-17)* **REQ-mobile-push**: Web-Push (VAPID) mit NotificationDevice-Registrierung und Token-Rotation. *(APNs/FCM/nativer Push verworfen — Web-Push-only, AD-17.)*
### Modul 37 — Plattform-Admin
- [ ] **REQ-plattform-admin-identität**: Admin-Welt auf `admin.hivegrid.de` (Host-Routing, Cookie-Domain-Trennung zu app.*) mit TOTP-Pflicht + MFA-Step-up; Admin-User ohne Tenant-Workspace. *(Scope-Schnitt 12.06.: getrennte AdminUser-Identität/AdminSession/AdminRBAC = M038/M039 → v2; v1 = Boilerplate-Modell User-Extension + `admin-mfa-gate`.)*
- [ ] **REQ-plattform-admin-features**: Tenant-Management, Subscription-Overrides, Feature-Flag-Verwaltung, BullMQ-Queue-Monitoring und Support-Inbox aus M39.
### Modul 38 — Help-Center (öffentlich)
- *(→ v2, Scope-Schnitt 2026-06-11)* **REQ-help-center**: Dateibasiertes Markdown-Help-Center mit Build-generiertem Index, client-seitiger FlexSearch-Suche, Deep-Links aus der App und SSR-SEO.
### Modul 39 — Help-Desk / Support
- [ ] **REQ-feedback-widget**: In-App Feedback-Widget (Bug/Feature/Frage/Sonstiges) mit Rate-Limit, Screenshot-Anhang via M23 und Platform-Admin-Support-Inbox in M37.
### Querschnitt — Integration-Contracts
- [ ] **REQ-integration-sidebar**: Alle neuen Modul-Bereiche müssen in der Sidebar-Konfiguration registriert sein (Registrierung in apps/web/app/application/sidebar/).
- [ ] **REQ-integration-routes**: Verbindliche URL-Schemata für Mandanten-App, Plattform-Admin, Customer-Portal, Public-Forms, Booking, Help und API (INTEGRATION-CONTRACTS §3).
- [ ] **REQ-integration-activity-wiring**: Jede schreibende Aktion mit Entitäts-Bezug muss logActivity() aus @hivegrid/activity aufrufen.
- [ ] **REQ-integration-audit-wiring**: Audit läuft automatisch über Prisma-Middleware (M21); Ausnahmen (S3-Upload, externe Webhooks) manuell über auditEvent() aus @hivegrid/audit.
- [ ] **REQ-integration-notification-wiring**: Benachrichtigungen immer über notify() aus @hivegrid/notifications, kein direkter Kanal-Zugriff in Modul-Code.
- [ ] **REQ-integration-view-model-pflicht**: Jede Route gibt im Loader ein View-Model zurück; UI-Components empfangen nur VM + Action-Callbacks, kein direkter DB-Zugriff.
- [ ] **REQ-integration-smoke-tests**: Jede neue Route bekommt einen Smoke-Test in e2e/smoke/{modul}.spec.ts gegen packages/ui-mock.
## v2 Requirements
**Definition (verbindlich):** v2 = alles, was gemacht werden MUSS — nur sequenziert nach dem v1-Launch. Kein Vielleicht-Backlog.
**Scope-Schnitt 2026-06-11 (15 REQs aus v1 verschoben — Definitionen oben mit *(→ v2)* markiert, Historie in `SCOPE-V1-CUTS.md`):**
- **Mobile (PWA-Ausbau, AD-17):** REQ-mobile-pwa, REQ-mobile-offline-sync, REQ-mobile-push — v1 = mobile-first responsive Web / PWA; v2 = installierbare PWA-Vertiefung (Expo/Capacitor verworfen — PWA-only; nativer Client + App-Store → v3)
- **Customer-Portal:** REQ-portal-datenmodell, REQ-portal-auth-magic-link, REQ-portal-projekt-sicht
- ~~**KI-Kür:** REQ-ki-hivemind, REQ-ki-rag-embeddings, REQ-ki-whisper — v1 baut Andock-Adapter~~ → **KI→MCP-Pivot ([[AD-26]]): zurückgestellt (v3-Kandidat); v2 liefert stattdessen `REQ-mcp-server` (MCP-Server, siehe [[VR-MCP]]/[[VD-MCP]]). Kein eigenes LLM/RAG/Whisper.**
- **Postfach-Sync:** REQ-email-sync-strategie, REQ-email-inbox-view — Sende-Domain + BCC-Brücke bleiben v1
- **Public-API:** REQ-public-api-read, REQ-public-webhooks
- **Help:** REQ-help-center — v1 = Minimal-FAQ; REQ-feedback-widget bleibt v1
- **Onboarding:** REQ-onboarding-wizard — v1 = Auto-SHK-Provisionierung ohne Wizard-UI
**Scope-Schnitt 2026-06-12 #12 (Abschluss-Runde, 3 REQs verschoben + 4 Dünnungen):**
- **KWP-Integration (ERSTES v2-Modul):** REQ-kwp-datenmodell, REQ-kwp-architektur (⚠ Recut: REST-API statt kwpsync.exe), REQ-kwp-schema-drift — Kalender-Realität: Hersteller-API-Zugang ~19.07. > v1-Launch ~10.07.; Callback-URL gemeldet, Andockpunkte in v1
- **Dünnungs-Notes (REQ bleibt v1):** Theme nur Hell/Dunkel (kein System-Modus) · Demo-Daten ohne KI-Walkthrough · Forms ohne personalisierte Links/JS-Snippet · Material-Listen ohne Lagerist-Sicht
**Scope-Schnitt 2026-06-12 (Boilerplate-Recheck, 1 REQ verschoben + Dünnungs-Notes an 9 REQs):**
- **Public-API-Paket:** REQ-auth-api-keys — wandert mit REQ-public-api-read/-webhooks; Boilerplate-`ApiKey`-Modell bleibt im Code
- **Als Dünnungs-Notes (REQ bleibt v1):** Notification-Bündelung/Quiet-Hours (M117), Sprach-Wechsler/EN-Templates (v1 DE-only, i18n-ready Pflicht), getrennte AdminUser-Identität (M038/M039; Auflagen: kein Tenant-Workspace, admin.hivegrid.de-Host-Routing + Cookie-Trennung), Datei-Versionierung/Office-Video-Preview/OCR (HEIC→JPG bleibt!), Dashboard-Drag&Drop (3 feste Rollen-Layouts), Audit-Retention-Konfigurierbarkeit/Legal-Hold
Bereits zuvor v2 (in Phase-1-Specs referenziert, nicht vollständig spezifiziert):
- **M11 WhatsApp**: Von M13 (Team-Chat) und M18 (KI-Layer/send-whatsapp-Action) referenziert; vollständige Spec und Implementierung verschoben auf Phase 2.
- **REQ-branding-tenant-phase2**: Tenant-Branding, White-Label und Custom-Domain (TenantBranding: logo, Farben, Custom-Domain) — Feature-Gate branding.white_label nur in Enterprise-Plan; verschoben auf Phase 2.
- **REQ-signatur-provider Fallback**: Einfacher PDF-Upload mit manueller Signatur-Erfassung als Fallback ohne externen Signatur-Provider — Phase 2.
- **DeepL-Übersetzungs-Pipeline (M30)**: Automatische Übersetzungsvorschläge via DeepL für Locale-Files — Phase 2.
## Out of Scope
Explizit ausgeschlossen. Dokumentiert zur Vermeidung von Scope-Creep.
| Feature | Reason |
|---------|--------|
| Konkrete Pricing-Stufen | Billing-Engine wird gebaut, Preise geparkt (AD-15); Geerkens auf Sonderkondition/Trial |
| Volle Migrations-Pipelines pro Altsystem | Sauberer Start; KWP-Sync füllt nach; HubSpot/Quiply als Read-only-Archiv, nur punktuelle CSV-Importe (AD-14) |
| ~~EU-Email-Provider-Wahl (AD-6)~~ | ✅ **GELOCKT 2026-06-11: Mailjet** (Boilerplate-verdrahtet, `MAILJET_*`) — kein offener Punkt mehr |
| ~~Captcha/Bot-Schutz (AD-7)~~ | ✅ **GELOCKT 2026-06-11: mCaptcha self-hosted** (`infra/mcaptcha/` fertig vorbereitet) — kein offener Punkt mehr |
| KWP Windows-Sync-Programm M089 (alte M19-Variante) | Entfällt durch offizielle KWP-API; M089–M095 vor Umsetzung neu schneiden; KWP wird als DataConnection type='rest-api' in M33a abgebildet |
## Traceability
Phase-Mapping aus ROADMAP.md (Stufe 2, revidiert auf 21 Phasen). Bau-Reihenfolge nach AD-11; jede Zeile genau einer Phase zugeordnet (100 % Coverage).
| Requirement | Phase | Status |
|-------------|-------|--------|
| REQ-integration-sidebar | Phase 1 | Pending |
| REQ-integration-routes | Phase 1 | Pending |
| REQ-integration-activity-wiring | Phase 1 | Pending |
| REQ-integration-audit-wiring | Phase 1 | Pending |
| REQ-integration-notification-wiring | Phase 1 | Pending |
| REQ-integration-view-model-pflicht | Phase 1 | Pending |
| REQ-integration-smoke-tests | Phase 1 | Pending |
| REQ-auth-multi-tenancy | Phase 2 | Pending |
| REQ-auth-methoden | Phase 2 | Pending |
| REQ-auth-rbac | Phase 2 | Pending |
| REQ-auth-user-lifecycle | Phase 2 | Pending |
| REQ-audit-datenmodell | Phase 1 | Pending |
| REQ-audit-retention-export | Phase 3 | Pending |
| REQ-audit-permissions | Phase 3 | Pending |
| REQ-notification-datenmodell | Phase 1 | Pending |
| REQ-notification-versand-pipeline | Phase 3 | Pending |
| REQ-i18n-architektur | Phase 1 | Pending |
| REQ-i18n-outbound | Phase 3 | Pending |
| REQ-feature-flags-system | Phase 1 | Pending |
| REQ-files-datenmodell | Phase 4 | Pending |
| REQ-files-upload-preview | Phase 4 | Pending |
| REQ-tasks-datenmodell | Phase 4 | Pending |
| REQ-tasks-reminder-archivierung | Phase 4 | Pending |
| REQ-apps-engine-datenmodell | Phase 5 | Pending |
| REQ-apps-engine-lifecycle | Phase 5 | Pending |
| REQ-crm-datenmodell | Phase 6 | Pending |
| REQ-crm-listen-views | Phase 6 | Pending |
| REQ-crm-detail-views | Phase 6 | Pending |
| REQ-lead-projekt-konvertierung | Phase 6 | Pending |
| REQ-crm-activity-stream | Phase 6 | Pending |
| REQ-crm-custom-felder | Phase 6 | Pending |
| REQ-crm-duplikat-erkennung | Phase 6 | Pending |
| REQ-crm-tags | Phase 6 | Pending |
| REQ-crm-permissions | Phase 6 | Pending |
| REQ-lead-inbox-liste | Phase 7 | Pending |
| REQ-lead-quellen-auto-anlage | Phase 7 | Pending |
| REQ-lead-status-workflow | Phase 7 | Pending |
| REQ-lead-anti-spam | Phase 7 | Pending |
| REQ-lead-statistiken | Phase 7 | Pending |
| REQ-lead-permissions | Phase 7 | Pending |
| REQ-projekt-kern-datenmodell | Phase 8 | Pending |
| REQ-pipeline-rechte-config | Phase 8 | Pending |
| REQ-projekt-kanban-listen-view | Phase 8 | Pending |
| REQ-projekt-pipeline-wechsel | Phase 8 | Pending |
| REQ-projekt-forecast-kpis | Phase 8 | Pending |
| REQ-projekt-sub-areas | Phase 9 | Pending |
| REQ-rechnung-sub-entity | Phase 9 | Pending |
| REQ-projekt-abnahme | Phase 9 | Pending |
| REQ-suche-datenmodell | Phase 11 | Pending |
| REQ-suche-hybrid | Phase 11 | Pending |
| REQ-suche-ui | Phase 11 | Pending |
| REQ-dashboard-datenmodell | Phase 11 | Pending |
| REQ-dashboard-widgets | Phase 11 | Pending |
| REQ-automation-datenmodell | Phase 12 | Pending |
| REQ-automation-trigger-library | Phase 12 | Pending |
| REQ-automation-action-library | Phase 12 | Pending |
| REQ-automation-flow-editor | Phase 12 | Pending |
| REQ-automation-schutz | Phase 12 | Pending |
| ~~REQ-ki-llm-gateway~~ → entfernt ([[AD-26]]) | ~~Phase 13~~ | Entfällt (KI→MCP) |
| REQ-mcp-server *(neu, [[AD-26]])* | v2-P4 (MCP) / [[VR-MCP]] | Pending |
| REQ-email-datenmodell | Phase 14 | Pending |
| REQ-marketing-datenmodell | Phase 14 | Pending |
| REQ-marketing-double-optin | Phase 14 | Pending |
| REQ-marketing-versand | Phase 14 | Pending |
| REQ-telefonie-datenmodell | Phase 15 | Pending |
| REQ-telefonie-provider-adapter | Phase 15 | Pending |
| REQ-chat-datenmodell | Phase 15 | Pending |
| REQ-chat-realtime | Phase 15 | Pending |
| REQ-chat-features | Phase 15 | Pending |
| REQ-kalender-datenmodell | Phase 16 | Pending |
| REQ-kalender-sync-adapter | Phase 16 | Pending |
| REQ-booking-datenmodell | Phase 16 | Pending |
| REQ-booking-slot-kalkulierung | Phase 16 | Pending |
| REQ-booking-integrationen | Phase 16 | Pending |
| REQ-form-datenmodell | Phase 16 | Pending |
| REQ-form-editor | Phase 16 | Pending |
| REQ-form-actions | Phase 16 | Pending |
| REQ-signatur-datenmodell | Phase 16 | Pending |
| REQ-signatur-provider | Phase 16 | Pending |
| REQ-hr-datenmodell | Phase 17 | Pending |
| REQ-hr-passwort-safe | Phase 17 | Pending |
| REQ-hr-urlaub-krank | Phase 17 | Pending |
| REQ-plattform-admin-identität | Phase 19 | Pending |
| REQ-plattform-admin-features | Phase 19 | Pending |
| REQ-billing-datenmodell | Phase 20 | Pending |
| REQ-billing-trial-dunning | Phase 20 | Pending |
| REQ-onboarding-demo-daten | Phase 20 | Pending |
| REQ-branding-theme-phase1 | Phase 20 | Pending |
| REQ-dsgvo-export | Phase 21 | Pending |
| REQ-dsgvo-tenant-deletion | Phase 21 | Pending |
| REQ-feedback-widget | Phase 21 | Pending |
**Coverage:**
- v1 requirements: 90 total (Scope-Schnitte 2026-06-11/12: 19 → v2; **Pivot-Neuzählung 16.06.: REQ-crm-lead-promotion entfällt −1, REQ-rechnung-sub-entity NEU +1 → Netto unverändert 90**)
- Mapped to phases: 90 (100 %)
- Unmapped: 0
**Pro-Phase-Verteilung:**
| Phase | Requirements |
|-------|--------------|
| Phase 1 — Fundament & Walking-Skeleton | 11 |
| Phase 2 — Identität & Mandantentrennung | 4 |
| Phase 3 — Querschnitts-Oberflächen | 4 |
| Phase 4 — Files & Tasks | 4 |
| Phase 5 — Apps-Engine & Integrations-Framework | 2 |
| Phase 6 — CRM-Kern | 9 |
| Phase 7 — Lead-Inbox | 6 |
| Phase 8 — Projekt & Pipelines (Teil 1: Kern + Pipeline-Engine) | 5 |
| Phase 9 — Projekt & Pipelines (Teil 2: Auftrags-Features + Sub-Areas) | 3 |
| Phase 10 — KWP-Integration | 0 (→ v2, erstes v2-Modul) |
| Phase 11 — Globale Suche & Dashboard | 5 |
| Phase 12 — Automation-Engine | 5 |
| Phase 13 — KI-Layer | 1 |
| Phase 14 — Email & Marketing | 4 |
| Phase 15 — Telefonie & Team-Chat | 5 |
| Phase 16 — Kalender, Booking, Forms & Signatur | 10 |
| Phase 17 — HR-Hub | 3 |
| Phase 18 — Customer-Portal | 0 (→ v2) |
| Phase 19 — Plattform-Admin | 2 |
| Phase 20 — Billing, Onboarding & Branding | 4 |
| Phase 21 — DSGVO & Launch-Reife | 3 |
| **Summe** | **90** |
---
*Requirements definiert: 2026-06-07 via /gsd:ingest-docs (Stufe 1). Phase-Mapping ergänzt: 2026-06-07 via /gsd:new-project (Stufe 2 — ROADMAP). Re-Mapping auf 21 Phasen: 2026-06-07 (Roadmap-Revision — dicke Buckets aufgeteilt). Scope-Schnitte 2026-06-11/12 (#1–#12): 19 REQs → v2 (90 v1, davon 3 KWP = erstes v2-Modul), Dünnungs-Notes an 13 REQs, AD-6/7-Lock nachgetragen. **R-REFIT 2026-06-16 (Pivot AD-20): Module 1–4 projekt-zentrisch nachgezogen; REQ-crm-lead-promotion → REQ-lead-projekt-konvertierung; Sales/Projekt-Reqs zu „Projekt & Pipelines" konsolidiert (REQ-projekt-kern-datenmodell, REQ-pipeline-rechte-config u.a.); REQ-rechnung-sub-entity NEU; Req-Summe neu gezählt = 90 (Netto unverändert: −1 lead-promotion / +1 rechnung).** *