53 KiB
HiveGrid Intel — Requirements (SPEC Extraction)
Extracted from 36 module specs + 1 INTEGRATION-CONTRACTS spec. One REQ-{slug} entry per major requirement cluster per spec. extracted: 2026-06-07
Modul 1 — CRM-Kern
source: _bmad-output/specs/M01-crm-kern.md
REQ-crm-datenmodell
Typisierte First-Class-Prisma-Tabellen für Contact, Company, Lead, ContactCompanyRelation, ContactEmail, ContactPhone, Activity, CustomFieldDefinition, CustomFieldValue, Tag, EntityTag. Kein polymorphes Entity/Row/RowValue-Schema (AD-2). RLS-Policies auf allen Tabellen (AD-1).
Acceptance criteria:
- Contact hat: id, tenant_id, salutation, title, first_name (Pflicht), last_name (Pflicht), address_*, birthdate, notes, language, assigned_to_user_id, lead_source, is_endkunde, archived_at
- Company hat: id, tenant_id, name (Pflicht), legal_form, vat_id, tax_number, industry, website, address_*, notes, assigned_to_user_id, archived_at
- Lead hat: id, tenant_id, first_name, last_name, email, phone (alle nullable), message, source (Enum), status (Enum: new|qualified|converted|lost|spam), assigned_to_user_id, converted_to_contact_id, converted_to_deal_id, archived_at
- ContactCompanyRelation: M:N mit role, is_primary, since_date, until_date
- Index auf tenant_id, archived_at, last_activity_at; trigram-Index auf Namensfeldern
REQ-crm-listen-views
Kontakt-Liste und Firmen-Liste mit server-seitiger Filter-/Sortier-/Paginierungs-Logik, Bulk-Actions, Export als CSV.
Acceptance criteria:
- Server-side-Filter (kein Client-side bei 10.000+ Einträgen)
- Cursor-basierte Pagination (50/Page, "Mehr laden")
- Bulk-Actions: Tag hinzufügen/entfernen, Verantwortlicher zuweisen, Archivieren, CSV-Export
- Filter: Verantwortlicher, Tags (AND/OR), Firma, Erstellt-Datum, Custom-Felder
- Spalten-Konfiguration per User (persistiert)
REQ-crm-detail-views
Kontakt-Detail, Firma-Detail, Lead-Detail mit Inline-Edit, Activity-Stream, verknüpften Entitäten, Custom-Feldern.
Acceptance criteria:
- Inline-Edit pro Feld mit Save/Cancel
- Activity-Stream-Komponente integriert
- Verknüpfungs-Verwaltung (Firmen ↔ Kontakt mit Rolle, M:N)
- Permissions: crm.read_own (404 statt 403 bei Fremdzugriff), crm.write, crm.delete, crm.admin
REQ-crm-lead-promotion
Lead-zu-Contact-Promotions-Modal mit Auto-Email-Match-Check und Transaktions-Sicherheit.
Acceptance criteria:
- 4 Optionen: (a) existing Contact aktualisieren, (b) neuen anlegen, (c) manuell zuordnen, (d) als Spam markieren
- Optional: Firma suchen/anlegen + Rolle, Deal anlegen (Default ja)
- Transaktionale Anlage: Contact + ggf. Company + ContactCompanyRelation + ggf. Deal; Lead.status = converted + FKs gesetzt
REQ-crm-activity-stream
Zentrale Activity-Tabelle (Event-Sourcing) mit allen Modulen als Schreiber; chronologische Stream-View pro Entität.
Acceptance criteria:
- Felder: id, tenant_id, created_at, actor_user_id, actor_kind, activity_type (Enum), subject_type, subject_id, related_entity_refs[], metadata, summary_text (DE, Pflicht)
- 18+ Activity-Typen (call_inbound, email_sent, deal_stage_changed, lead_promoted, automation_triggered usw.)
- Activities sind read-only (nicht löschbar)
- Index auf tenant_id, subject_type, subject_id, created_at DESC
- Filter nach Typ, Actor, Zeitraum; Cursor-basierte Pagination
REQ-crm-custom-felder
CustomFieldDefinition + CustomFieldValue pro Tenant, anwendbar auf Contact/Company/Lead/Deal.
Acceptance criteria:
- Typen: text, number, date, select, multiselect, boolean, url, email
- field_key (snake_case, unique pro applicable_to + tenant) unveränderlich; nur label änderbar
- Verwaltungs-Route: Drag-&-Drop-Sortierung, Add/Edit/Archive/Hard-Delete
- Anwendung in Listen-Views als Filter und Spalte (Phase 1)
- SHK-Branchen-Template-Defaults: geseedet beim Tenant-Anlegen (nicht hardcoded)
REQ-crm-duplikat-erkennung
Live-Match-Check beim Anlegen + Bulk-Duplikat-Tool für Admins.
Acceptance criteria:
- Hard-Match: Email exakt (case-insensitive), Telefon exakt (normalisiert)
- Soft-Match: Name + Firma identisch, Name + PLZ identisch
- Live-Check debounced beim Tippen von Email/Telefon
- Bulk-Duplikat-Tool: Side-by-Side-Anzeige, Field-by-Field-Merge, Skip-Funktion
- Permission: Inline-Hinweis für crm.write; Bulk-Tool nur crm.admin
REQ-crm-tags
Tag-System mit ad-hoc-Erstellung, Farbgebung, Entity-übergreifend.
Acceptance criteria:
- Tag: id, tenant_id, name (unique pro Tenant + applicable_to), color (8 vordefinierte Farben), applicable_to[]
- Ad-hoc-Erstellung mit crm.write-Permission
- Verwaltungs-Route: Umbenennen, Farbe ändern, Merge, Hard-Delete, Auto-Cleanup-Toggle
- Verwendung in Listen-Filter (AND/OR), Automation-Engine als Trigger/Action
REQ-crm-permissions
Permission-Bundle crm.* für alle CRM-Entitäten.
Acceptance criteria:
- Permissions: crm.read_own, crm.read_all, crm.write, crm.delete, crm.admin
- Owner-Check: 404 (nicht 403) bei Fremdzugriff mit read_own
- Server-side Permission-Filter in allen Listen (Permissions-aware-Default, AV #5)
- Audit-Trail für alle schreibenden Aktionen (AV #6)
Modul 2 — Lead-Inbox
source: _bmad-output/specs/M02-lead-inbox.md
REQ-lead-inbox-liste
Lead-Inbox als Arbeitsplatz mit Status-Filter, Triage-Quick-Actions, Bulk-Operations.
Acceptance criteria:
- Default-Filter: Status new + qualified; Spam ausgeblendet; Konvertierte ausgeblendet
- Quick-Actions pro Zeile ohne Drilldown: Zuweisen, Status setzen, Zu Contact promovieren, Spam markieren
- Saved Views (User-spezifisch, max. 5 in Phase 1)
- Real-time-Refresh bei neuem Lead (SSE oder Polling 30 Sek)
- Index auf tenant_id, status, created_at DESC; trigram auf email, phone, last_name
REQ-lead-quellen-auto-anlage
Automatische Lead-Anlage aus Form-Submission, eingehender Mail, AirCall-Inbound-Anruf.
Acceptance criteria:
- Form → Lead (source=form, metadata.form_id, metadata.submission_id)
- Mail → Lead (source=email, kein Auto-Merge, Mensch entscheidet)
- AirCall-Inbound unbekannte Nummer → Lead (source=phone, Verantwortlicher = AirCall-Empfänger)
- Manuell: Route /leads/new mit Inline-Match-Check
- Trigger für Automation-Engine: lead.created-Event
REQ-lead-status-workflow
Status-Enum (new|qualified|converted|lost|spam) mit definierten Übergängen und DSGVO-Auto-Lösch.
Acceptance criteria:
- Spam → Hard-Delete nach 30 Tagen (täglicher Cron)
- Lost → Hard-Delete nach 90 Tagen (Tenant-Admin-konfigurierbar, 0=nie)
- converted ist Terminal-Status (nicht änderbar)
- Vor Hard-Delete: anonymisierter Activity-Trail bleibt, Audit-Log-Eintrag bleibt
REQ-lead-anti-spam
Rate-Limiting und Anomalie-Detection für Lead-Quellen.
Acceptance criteria:
- Hard-Limit: 100/h pro Quelle, 20/h pro IP (konfigurierbar)
- Anomalie-Detection: 10x-Normal-Rate-Spike → Auto-Pause + Tenant-Admin-Notification
- Auto-Mark-as-Spam-Heuristiken optional (IP-Blocklist, Disposable-Email, Honeypot, <3-Sek-Submission)
- Quarantäne-Modus (Standard): Spam-Verdacht → Status new mit Marker, KEIN Auto-Spam
- Klartext-Notification mit [Reaktivieren]-Aktion
REQ-lead-statistiken
Statistiken-Page mit KPIs, Quellen-Aufschlüsselung, Trend-Charts.
Acceptance criteria:
- KPI-Kacheln: Eingegangene Leads, Konvertierungsrate Lead→Contact, Lead→Deal-won, Reaktionszeit, Spam-Quote, Open-Leads
- Aufschlüsselung nach Quelle, Verantwortlichem, Tag, Wochentag/Tageszeit, Status-Verteilung
- Aggregat-Query mit Materialized View oder Cron-aggregierter Statistik-Tabelle (täglich neu)
- Permission: read_own = nur eigene; Verantwortlichen-Aufschlüsselung nur mit read_all
REQ-lead-permissions
Permission-Bundle leads.* mit Owner-Check-Logik.
Acceptance criteria:
- Permissions: leads.read_own, leads.read_all, leads.write, leads.delete, leads.admin
- Promotion: erfordert leads.write UND crm.write
- Bulk-Export: leads.admin
- Permission-aware Server-side-Filter in allen Listen
Modul 3 — Sales-Pipeline
source: _bmad-output/specs/M03-sales-pipeline.md
REQ-sales-datenmodell
Multi-Pipeline-Architektur mit Pipeline, PipelineStage, Deal, LostReason, HiveNumberSeq.
Acceptance criteria:
- Pipeline hat: id, tenant_id, name, is_default, position, archived_at
- PipelineStage hat: stage_kind (open|won|lost), win_probability (0–100), auto_archive_after_days, color
- Validation: Pipeline muss mind. 1 won- und 1 lost-Stage haben
- Deal hat: deal_number (fortlaufend über HiveNumberSeq), pipeline_id, stage_id, title (Pflicht), volume (numeric 12,2), currency, expected_close_date, actual_close_date, contact_id (Pflicht), company_id, lead_id, lost_reason_id, won_handoff_project_id
- LostReason: Pflicht bei Stage=lost; SHK-Template seedet 5 Standard-Reasons
REQ-sales-kanban-listen-view
Kanban-View (Drag-&-Drop) und Listen-View (tabellarisch), beide mit Filter, Bulk-Actions, Real-Time-Updates.
Acceptance criteria:
- Drag in won-Stage: Bestätigungs-Dialog mit Won-Handoff-Option
- Drag in lost-Stage: Bestätigungs-Dialog erzwingt lost_reason-Auswahl
- Reverse-Window: Won/Lost innerhalb 24h zurücknehmbar
- Real-Time-Updates bei Stage-Wechsel durch andere User (WebSocket oder SSE)
- Aggregat-Cache pro Stage (Anzahl + Volumen-Summe), invalidiert bei Stage-Wechsel
REQ-sales-deal-lifecycle
Deal-Anlage aus mehreren Quellen, Stage-Wechsel-Validation, Won-Handoff zu M4, Auto-Archive.
Acceptance criteria:
- Anlage-Quellen: manuell, Lead-Promotion, Form-Submission, Email, Anruf, Automation
- Won-Handoff: Trigger M4 zur Projekt-Anlage mit Mapping Deal-Felder → Projekt-Felder; Deal.won_handoff_project_id gesetzt
- Auto-Archive: Won nach 30 Tagen, Lost nach 90 Tagen (konfigurierbar)
- Stage-Stuck-Detection: Daily-Cron markiert Deals länger als Schwelle in Stage; Automation-Trigger deal.stuck.in_stage
REQ-sales-forecast-kpis
Forecast-Berechnung, KPIs pro Vertriebler, Stage-Conversion-Rates, Lost-Reason-Auswertung.
Acceptance criteria:
- Pipeline-Forecast: Summe volume × stage.win_probability / 100 (nach Zeitraum aufteilbar)
- KPIs: aktive Deals, Won-Rate, Cycle-Time, Stuck-Deals, Aktivitäts-Metriken
- Stage-Conversion-Rates aus Activity-Daten
- Aggregat-Cache pro Pipeline + Zeitraum
REQ-sales-field-level-permissions
Field-Level-Permissions für Volumen und Aggregate.
Acceptance criteria:
- Permissions: deals.read_volume_own, deals.read_volume_all, deals.read_aggregates, deals.read_close_date_all
- Volumen ohne Permission: zeigt "—" (kein expliziter Fehler)
- Aggregat-Volumen pro Stage-Spalte ausgeblendet ohne read_aggregates
- SHK-Rollen-Template-Defaults geseedet
Modul 4 — Auftrags-/Projektpipeline
source: _bmad-output/specs/M04-auftragspipeline.md
REQ-projekt-datenmodell
ProjectPipeline, ProjectPipelineStage, Project, ProjectMember, ScheduleEntry, AcceptanceProtocol, ProjectTemplate.
Acceptance criteria:
- Multi-Pipeline analog M03 (SHK-Pipelines geseedet)
- Project: id, tenant_id, deal_source_id, pipeline_id, stage_id, title, volume, contact_id, company_id, assigned_to_user_id, archived_at
- ProjectMember: Rollen-basiert (Projektleiter, Bauleiter, Monteur)
- AcceptanceProtocol: digitale Abnahme mit Unterschrift
- ProjectTemplate: wiederverwendbare Vorlagen mit Stages + Standard-Tasks
REQ-projekt-plantafel
Plantafel-Ansicht für Ressourcen-Scheduling und Auftragszuweisung.
Acceptance criteria:
- ScheduleEntry: project_id, user_id (Monteur), date, start_time, end_time
- Plantafel zeigt Auftrage pro Monteur/Tag
- Konflikte erkennbar (Überschneidungen)
- Bearbeitung offline möglich (AD-17)
REQ-projekt-abnahme
Abnahme-Protokoll direkt im Projekt mit digitaler Unterschrift.
Acceptance criteria:
- AcceptanceProtocol: project_id, signed_by_customer_name, signature_data (Base64), signed_at, form_answers (JSONB)
- Abnahme-Templates aus M05 Form-Builder verwendbar
- Offline-Abnahme mit Sync-Queue (AD-17)
Modul 5 — Form Builder
source: _bmad-output/specs/M05-form-builder.md
REQ-form-datenmodell
Form, FormField, FormSubmission, FormSubmissionAnswer, FormFile, FormLink, FormAction, FormActionLog.
Acceptance criteria:
- Form: id, tenant_id, slug (unique), title, description, status (draft|published|archived), settings (JSONB)
- FormField: Typen text, email, phone, number, date, select, multiselect, checkbox, file, signature, textarea, hidden
- FormSubmission: form_id, tenant_id, submitted_at, ip_address, answers (JSONB), source_url
- FormLink: öffentliche Share-URL + embed_code
- FormAction: Lead-anlegen, Deal-anlegen, Task-anlegen, Webhook, Email, Notification
REQ-form-editor
Drag-&-Drop-Form-Editor mit Echtzeit-Vorschau, Validierung, Conditional Logic.
Acceptance criteria:
- Drag-&-Drop für Feld-Reihenfolge
- Conditional-Logic: Feld X anzeigen wenn Feld Y = Wert Z (Phase 1: einfache Bedingungen)
- Form-Templates (SHK-Vorlagen geseedet)
- Embed-Code für iFrame-Einbettung
- Honeypot-Feld (Anti-Spam-Kooperation mit M02)
REQ-form-actions
Form-Actions nach Submission: Lead/Deal/Task anlegen, Webhook, Email, Automation-Trigger.
Acceptance criteria:
- Field-Mapping konfigurierbar (Form-Feld → Ziel-Entitäts-Feld)
- Multiple Actions pro Form möglich
- FormActionLog: Protokollierung jeder Action-Ausführung
- Fehler in Action: Submission selbst bleibt gespeichert; ActionLog markiert Fehler
Modul 6 — Booking
source: _bmad-output/specs/M06-booking.md
REQ-booking-datenmodell
BookingPage, BookingPageProvider, AvailabilityRule, AvailabilityException, Appointment.
Acceptance criteria:
- BookingPage: tenant_id, slug (unique), title, duration_minutes, buffer_before/after, max_advance_days, min_notice_hours
- AvailabilityRule: weekday, start_time, end_time, timezone
- AvailabilityException: specific_date, is_blocked, slots[]
- Appointment: booking_page_id, contact_id (oder anonymer Guest), start_at, end_at, status (scheduled|completed|cancelled), confirmation_token
REQ-booking-slot-kalkulierung
Slot-Berechnung unter Berücksichtigung von Verfügbarkeitsregeln, Ausnahmen, Kalender-Sync und Puffer.
Acceptance criteria:
- Slots berechnet aus AvailabilityRules + AvailabilityExceptions + verbundene Kalender-Events (M25)
- Puffer vor/nach Termin berücksichtigt
- Timezone-aware Darstellung
- Public Booking Page ohne Auth erreichbar (Route /buch/{tenant}/{slug})
REQ-booking-integrationen
Lead-Inbox-Integration, Activity-Stream, Form-Submission-Verknüpfung, Bestätigungs-Email.
Acceptance criteria:
- Neuer Termin → Appointment-Bestätigungs-Email (via M09/M22)
- Termin → Activity-Eintrag appointment_scheduled
- Kein passender Contact → Lead angelegt (source=booking)
- iFrame-Embed-Code verfügbar
Modul 7 — Angebot + Signatur
source: _bmad-output/specs/M07-angebot-signatur.md
REQ-signatur-datenmodell
DealSignatureDocument, DealSignatureSigner, DealSignatureStatusTransition, SignatureProviderConnection.
Acceptance criteria:
- DealSignatureDocument: deal_id, provider (pandadoc|docusign), provider_doc_id, status (draft|sent|viewed|signed|declined|expired), pdf_url
- DealSignatureSigner: document_id, name, email, role, signed_at, signature_provider_signer_id
- Multi-Signer-Workflow: Reihenfolge konfigurierbar (sequenziell oder parallel)
- SignatureWebhookEvent: Inbound-Webhooks von PandaDoc/DocuSign prozessiert
REQ-signatur-provider
PandaDoc/DocuSign-Integration über Apps-Engine (M33a).
Acceptance criteria:
- OAuth-Connect-Flow via M33a DataConnection
- PDF-Upload + Provider-spezifisches Feld-Mapping
- Webhook-Verarbeitung für Status-Updates
- Fallback: einfacher PDF-Upload mit manueller Signatur-Erfassung (Phase 2)
Modul 9 — Email-Inbox
source: _bmad-output/specs/M09-email-inbox.md
REQ-email-datenmodell
EmailIntegrationMailbox, EmailIntegrationMessage, EmailIntegrationSyncCursor, TenantSendingDomain, TenantInboundAddress.
Acceptance criteria:
- EmailIntegrationMailbox: tenant_id, provider (gmail|outlook), oauth_token (verschlüsselt AD-8), sync_status, last_synced_at
- EmailIntegrationMessage: mailbox_id, provider_message_id (unique), thread_id, from_email, subject, body_text, body_html, direction (inbound|outbound), linked_contact_id, linked_lead_id
- TenantSendingDomain: DKIM/SPF/DMARC-Einträge; Scaleway für inbound
- Cursor-basierter Sync (Gmail API History, Microsoft Graph delta)
REQ-email-sync-strategie
Bidirektionaler Sync Gmail/Outlook mit Provider-Adapter-Pattern.
Acceptance criteria:
- ProviderAdapter-Interface: connect(), sync(), send(), getThread()
- GmailAdapter und OutlookAdapter implementieren Interface
- Gmail: Pub/Sub-Webhooks für inbound; Outlook: Microsoft Graph subscriptions
- Auto-Matching: Absender-Email → Contact/Lead (kein Auto-Merge, nur Link)
- Unbekannter Absender → Lead angelegt (source=email)
REQ-email-inbox-view
Inbox-View, Compose, Thread-View mit Permission-Scoping.
Acceptance criteria:
- Inbox: alle eingehenden Mails, gefiltert per Mailbox + Status (ungelesen/gelesen)
- Thread-View: chronologisch, mit verknüpftem Contact/Lead/Deal sichtbar
- Compose mit Vorauffüllung Empfänger (aus CRM-Context)
- Gesendet via verbundene Mailbox oder Scaleway TEM als Fallback
Modul 10 — Email-Marketing
source: _bmad-output/specs/M10-email-marketing.md
REQ-marketing-datenmodell
Campaign, OutboundEmail, OutboundEmailOpen/Click, EmailTemplate, EmailSender, RecipientSegment, EmailSuppressionList.
Acceptance criteria:
- Campaign: tenant_id, name, status (draft|scheduled|sending|sent|cancelled), subject, from_sender_id, recipient_segment_id, scheduled_at, sent_at, stats (JSONB)
- OutboundEmail: campaign_id, contact_id, email_address, status (queued|sent|bounced|spam|unsubscribed), sent_at
- Tracking: pixel für Opens (1x1 PNG), Link-Rewriting für Clicks; DSGVO-konform (nur aggregiert publishen)
- EmailSuppressionList: hard-bounce, unsubscribe, spam-report auto-hinzufügen
REQ-marketing-double-optin
Double-Opt-In-Workflow mit DSGVO-Compliance.
Acceptance criteria:
- Opt-In per Form-Submission (M05) → Bestätigungs-Email → Klick-Confirmation-Token
- Status: pending_confirmation → confirmed → aktiv
- Unsubscribe: One-Click (Liste in jeder Mail Pflicht per Gesetz)
- Suppression-List-Check vor jedem Versand
REQ-marketing-versand
BullMQ-basierter Versand mit Rate-Limiting, SMTP-Provider-Abstraktion (Scaleway TEM).
Acceptance criteria:
- BullMQ-Queue für async Versand; Rate-Limit konfigurierbar (Provider-abhängig)
- Bounce-Handling: soft bounce → retry; hard bounce → suppression
- Automation-Engine-Integration: Trigger campaign.sent, Aktion send-campaign-email
Modul 12 — Telefonie (AirCall)
source: _bmad-output/specs/M12-telefonie.md
REQ-telefonie-datenmodell
TelephonyConnection, TelephonyUserBinding, TelephonyCallSession, TelephonyWebhookEvent.
Acceptance criteria:
- TelephonyConnection: tenant_id, provider=aircall, oauth_tokens (verschlüsselt AD-8), status
- TelephonyUserBinding: connection_id, user_id, aircall_user_id (1:1 Mapping)
- TelephonyCallSession: session_id (provider), direction (inbound|outbound), from_number, to_number, contact_id, lead_id, deal_id, recording_url, transcript_url, duration_seconds, status
REQ-telefonie-provider-adapter
TelephonyProviderInterface mit AirCallAdapter; Click-to-Call, Inbound-Webhook-Verarbeitung.
Acceptance criteria:
- Provider-Interface: initiateCall(), handleInboundWebhook(), getRecording()
- Click-to-Call aus Contact/Deal/Lead-Detail-View
- Inbound-Webhook: AirCall sendet Ereignisse → matching → Contact/Lead
- Unbekannte Nummer → Lead (source=phone)
- Activity-Eintrag call_inbound / call_outbound pro Session
Modul 13 — Team-Chat
source: _bmad-output/specs/M13-team-chat.md
REQ-chat-datenmodell
TeamChat (Channel), TeamChatMember, TeamChatMessage, TeamChatPinnedMessage, TeamChatReaction, TeamChatThread, TeamChatRead.
Acceptance criteria:
- 3 Channel-Typen: public (alle), private (invite-only), entity-linked (zu Contact/Deal/Projekt gebunden)
- Nachrichten: id, channel_id, user_id, body (Markdown), attachments[], reply_to_message_id, edited_at, deleted_at
- Threads: verankert an Message (wie Slack)
- Reactions: Emoji per Message, mehrere User pro Emoji
- TeamChatRead: Last-Read-Pointer pro User pro Channel für Ungelesen-Zähler
REQ-chat-realtime
WebSocket-basiertes Real-Time-Messaging mit Presence, Typing-Indicator, Read-Receipts.
Acceptance criteria:
- WebSocket-Room-Layer (AD-9): ein Room pro Channel
- Presence: User online/offline/away über Redis
- Typing-Indicator: debounced
- Push-Notifications bei Mention oder DM (via M22/FCM/APNs)
- Redis-Pub/Sub für Scale-Out
REQ-chat-features
Link-Previews, File-Uploads, Mentions, Such-Funktion, gelinkte Channels.
Acceptance criteria:
- Link-Preview: OGP-Fetch server-side (kein Client-Tracking)
- File-Upload via M23 (Datei-Speicher)
- @Mention auto-complete mit User-Vorschlägen; Notification an genannten User
- Suche im Chat-Verlauf (Postgres-FTS auf body)
- Entity-linked Channel: sichtbar im Deal/Projekt-Detail
Modul 14 — HR-Hub
source: _bmad-output/specs/M14-hr-hub.md
REQ-hr-datenmodell
HrEmployeeProfile, HrAnnouncement, EmployeeVacationRequest, EmployeeSickLeaveReport, EmployeePayslip, EmployeePasswordSafeVault/Entry, HrSurvey, HrRequest.
Acceptance criteria:
- HrEmployeeProfile: user_id (1:1), position, department, entry_date, emergency_contact, profile_photo_url, manager_user_id
- EmployeeVacationRequest: user_id, start_date, end_date, days_count, status (pending|approved|rejected|cancelled), approver_user_id
- EmployeePayslip: verschlüsselt (AES-256-GCM mit Per-Tenant-DEK, AD-8), nur für betreffenden MA + HR sichtbar
- EmployeePasswordSafeVault/Entry: AES-256-GCM verschlüsselt (AD-8), KMS-gestützt
REQ-hr-passwort-safe
Verschlüsselter Passwort-Safe pro Mitarbeiter mit KMS-backed Envelope-Encryption.
Acceptance criteria:
- Verschlüsselung: Per-Tenant-DEK via Scaleway Key Manager (AD-8)
- Vault-Entries: title, username, password_encrypted, url, notes_encrypted
- Export nur für den MA selbst (und HR-Admin)
- Audit-Trail für jeden Zugriff (AV #6)
- DSGVO-Export (M35) inkludiert Vault-Daten
REQ-hr-urlaub-krank
Urlaubs-Anfrage-Workflow und Krankmeldungs-Erfassung mit Approval-Flow.
Acceptance criteria:
- Vacation-Request: mehrstufiger Approval (Manager → HR), konfigurierbar
- Abwesenheits-Kalender (Übersicht für HR + Projektleiter)
- SickLeaveReport: user_id, start_date, back_expected_date, uploaded_certificate_file_id
- Integration M25 (Calendar): Abwesenheit als Kalender-Event
Modul 15 — Customer-Portal
source: _bmad-output/specs/M15-customer-portal.md
REQ-portal-datenmodell
PortalUser, CustomerPortalSession, CustomerPortalProjectAccess, CustomerPortalProjectDocument, PortalConfiguration, PortalEmailTemplate.
Acceptance criteria:
- PortalUser: tenant_id, email (unique pro Tenant), display_name, linked_contact_id, status (active|invited|deactivated)
- CustomerPortalSession: Magic-Link-Auth (kein Passwort in Phase 1); 24h-Token
- CustomerPortalProjectAccess: explizite Freigabe pro Projekt durch Tenant-Admin
- PortalConfiguration: Tenant-Admin konfiguriert: enabled, logo, welcome_text, visible_sections[]
REQ-portal-auth-magic-link
Magic-Link-Authentication für Endkunden (separate Auth-Welt, kein Generalschlüssel, AD-3).
Acceptance criteria:
- Magic-Link per Email (Token 24h gültig, one-time)
- CustomerPortalSession: IP-gebunden, 8h-Inaktivität
- Kein Zugriff auf Tenant-App-Daten (vollständig getrennte Route /portal/{tenant}/...)
- DSGVO-Lösch-Workflow: PortalUser-Löschung entfernt Zugänge + Activity-Trail
REQ-portal-projekt-sicht
Projekt-Sicht für Endkunden: Status, Dokumente, File-Upload, Portal-Forms.
Acceptance criteria:
- Nur Projekte sichtbar, die explizit freigegeben (CustomerPortalProjectAccess)
- Dokumente: Tenant-Admin released CustomerPortalProjectDocument (nicht automatisch alle Files)
- File-Upload: Endkunde lädt Dokumente hoch (via M23, tenant-prefix)
- Portal-Forms: M05-Forms im Portal-Kontext ausfüllbar
- Default-Sichtbarkeit für neue Funktionen: NICHT sichtbar (AD-18)
Modul 17 — Automation Engine
source: _bmad-output/specs/M17-automation-engine.md
REQ-automation-datenmodell
AutomationRule, AutomationRuleStep, AutomationExecution, AutomationStepExecution, AutomationCredential, AutomationTemplate.
Acceptance criteria:
- AutomationRule: flow_data (JSON Graph: Nodes + Edges), enabled, created_via (manual|template|ki_natural_language), executions_count_30d
- AutomationRuleStep: node_type (trigger|action|condition|delay|loop), config (JSONB), position, connections[]
- AutomationExecution: rule_id, trigger_payload, status (running|completed|failed|cancelled), started_at, finished_at, retries
- AutomationStepExecution: execution_id, step_id, input, output, status, error_message
REQ-automation-trigger-library
Phase-1-Trigger-Library (Geerkens-fokussiert) über alle Module.
Acceptance criteria:
- CRM: lead.created, lead.status_changed, contact.created, contact.updated
- Sales: deal.created, deal.stage_changed, deal.won, deal.lost, deal.stuck
- Projekte: project.created, project.stage_changed
- Email: email.received
- Forms: form.submitted
- Kalender: appointment.scheduled
- Zeit-Trigger: cron (Schedule), delay
- Webhook: incoming_webhook
REQ-automation-action-library
Phase-1-Action-Library über alle Module.
Acceptance criteria:
- CRM: create-contact, update-contact, create-lead, assign-lead, set-tag, create-deal, update-deal-stage
- Notifications: send-notification, send-email, send-whatsapp (Phase 2)
- KWP: kwp.push_auftrag
- HTTP: http-request (externe Webhooks)
- Tasks: create-task
- Automation-interne: if/else, delay, loop
REQ-automation-flow-editor
Graph-basierter visueller Flow-Editor mit KI-Erstellung per natürlicher Sprache.
Acceptance criteria:
- Graph-Bibliothek (Flow-kompatibel) mit Nodes + Edges
- KI-Erstellung: User beschreibt auf Deutsch → KI generiert flow_data (AD-16)
- Dry-Run: Execution ohne echte Seiteneffekte, zeigt expected Steps + Output
- 24h-Undo für alle Automation-Executions (reversible Actions)
REQ-automation-schutz
Loop-Guard, Rate-Limit, Anomalie-Detection, Idempotenz.
Acceptance criteria:
- Loop-Guard: max. 10 Re-Trigger derselben Rule durch eigene Executions innerhalb 60 Sek → Auto-Disable + Alert
- Rate-Limit pro Rule: max. 1000 Executions/24h (konfigurierbar)
- Idempotency-Key per Execution (dedupliziert Retry-Storm)
- Resume-Mode: bei transientem Fehler in Step N → Retry ab Step N (nicht ab Step 0)
- Trigger-Volumen-Metering: Zählung pro Tenant für Billing (AD-15)
Modul 18 — KI-Layer
source: _bmad-output/specs/M18-ki-layer.md
REQ-ki-llm-gateway
EU-only LLM-Gateway mit Multi-Provider-Abstraktion und Token-Tracking.
Acceptance criteria:
- Unterstützte Provider: Scaleway, Mistral, AlephAlpha (alle EU-ansässig, LP-13)
- LlmGatewayProvider: provider_key, base_url, api_key_encrypted (AD-8), models[], status
- AiTokenUsage: tenant_id, user_id, provider, model, prompt_tokens, completion_tokens, cost_eur, created_at
- AiCredits: Pro-Tenant-Credit-Konto; Deduktion bei Nutzung; Preis-Modell Pay-as-you-go (AD-15)
REQ-ki-rag-embeddings
RAG-Pipeline mit pgvector für semantische Suche und KI-Kontext.
Acceptance criteria:
- TenantEmbedding: entity_type, entity_id, embedding (vector(1024)), model_id, created_at
- Embeddings via Scaleway EU-Endpoint (1024-dim, AD-5)
- Outbox-Pattern für Embedding-Job-Queue
- Retrieval: Top-K similar via pgvector (<=> cosine distance), gefiltert nach tenant_id + RLS
REQ-ki-whisper
Whisper-Transkription für Anruf-Aufzeichnungen und Sprachnotizen.
Acceptance criteria:
- Whisper-Job: audio_file_id → text_transcript, language_detected
- EU-Whisper-Endpoint (Scaleway)
- Transkript gespeichert in TelephonyCallSession.transcript_url (M12)
- Nutzung: Token-Tracking, AiCredits-Deduktion
REQ-ki-hivemind
HiveMind-KI-Assistent: kontextueller Chat-Assistent mit RAG-Anbindung.
Acceptance criteria:
- Conversation: tenant_id, user_id, context_entity_type, context_entity_id, messages[]
- ConversationMessage: role (user|assistant|system), content, token_count, model_id
- Sicherheit: Promptfoo-basiertes Testing; AV #20 (KI darf keine destruktiven Aktionen ohne User-Bestätigung ausführen)
Modul 19 — KWP-Integration
source: _bmad-output/specs/M19-kwp-integration.md
REQ-kwp-datenmodell
KwpSettings, KwpRegistry, KwpProjectQueue, KwpProjectNumberSequence, KwpApiKey, KwpDocument, KwpErrorReport, KwpSchemaSnapshot.
Acceptance criteria:
- KwpSettings: tenant_id, data_connection_id (FK M33a DataConnection), kwp_db_host/port/name NICHT in Cloud gespeichert (DSGVO)
- KwpRegistry: mapping HiveGrid-entity_id ↔ kwp_entity_id (bidirektional)
- KwpProjectQueue: Cloud-Side-Queue für Push-Operationen (Auftrag-Push zu KWP)
- KwpApiKey: Token für kwpsync.exe-Auth (verschlüsselt AD-8)
- KwpSchemaSnapshot: letztes bekanntes MSSQL-Schema (Basis für Schema-Drift-Sentinel)
REQ-kwp-architektur
Drei-Komponenten-Architektur: HiveGrid Cloud, kwpsync.exe (Windows-Client), KWP MSSQL-DB.
Acceptance criteria:
- kwpsync.exe: Windows-Service, Polling-Loop 30 Sek, Heartbeat 5 Min, lokale SQLite-Queue, Auto-Update
- Bidirektional: HiveGrid→KWP (Auftrags-Push via Automation M17-Action kwp.push_auftrag), KWP→HiveGrid (Stammdaten-Pull, Belege)
- Adapter-Pattern: KWP als DataConnection type=windows_client in M33a Apps-Engine
- KWP-API-Recut (siehe ADR-Notiz): bei nativer API wird windows_client zu rest-api
REQ-kwp-schema-drift
Schema-Drift-Sentinel für MSSQL-Schema-Änderungen.
Acceptance criteria:
- KwpSchemaSnapshot: regelmäßig aktualisiert durch kwpsync.exe
- Drift-Detection: Vergleich aktuelle Schema vs. Snapshot → Alert wenn Spalten/Tabellen fehlen
- Tenant-Admin-Notification + KwpErrorReport bei Drift
- Adapter-Interface-Test gegen Schema-Snapshot
Modul 20 — Dashboard
source: _bmad-output/specs/M20-dashboard.md
REQ-dashboard-datenmodell
Dashboard, DashboardLayout, WidgetCatalog, WidgetInstance.
Acceptance criteria:
- Dashboard: tenant_id, user_id (null = tenant-wide), name, is_default
- DashboardLayout: dashboard_id, layout_data (JSON: react-grid-layout-kompatibel)
- WidgetInstance: dashboard_id, widget_type (aus WidgetCatalog), config (JSONB), position, size
- Role-Default-Layouts: per Rolle vorkonfigurierte Dashboard-Layouts (SHK-Template geseedet)
REQ-dashboard-widgets
Widget-Katalog mit Datenquellen aus Sales, Projekte, Tasks, HR, KI.
Acceptance criteria:
- Sales-Widgets: Pipeline-Forecast, Deal-Funnel, Won-Rate, Top-Vertriebler
- Projekt-Widgets: Offene Aufträge, Plantafel-Übersicht, Abnahmen-Queue
- Task-Widgets: My-Tasks, Overdue-Tasks, Team-Tasks
- HR-Widgets: Abwesenheiten, Ankündigungen
- KI-Widget: AI-Credit-Usage
- Realtime-Update via WebSocket oder SSE für Live-Daten (AD-9)
- Aggregat-Cache mit TTL (konfigurierbar pro Widget-Typ)
Modul 21 — Audit-Log
source: _bmad-output/specs/M21-audit-log.md
REQ-audit-datenmodell
AuditEntry, AuditExportJob, AuditRetentionPolicy (append-only).
Acceptance criteria:
- AuditEntry: id (UUID), tenant_id (null=plattformweit), created_at, actor_user_id, actor_type (user|system|automation|admin), action (string), entity_type, entity_id, before_state (JSONB), after_state (JSONB), ip_address, previous_hash, current_hash (SHA-256-Kette)
- Hash-Kette: current_hash = SHA256(previous_hash + payload) — Tamper-Nachweisbarkeit
- Append-only: kein UPDATE oder DELETE auf AuditEntry (DB-Constraint)
- Prisma-Middleware: alle write-Operationen auto-generieren AuditEntry (AV #6)
REQ-audit-retention-export
Retention-Policy, Legal-Hold, Export-Jobs, DSGVO-Compliance.
Acceptance criteria:
- AuditRetentionPolicy: tenant_id, retention_days (Default 3650 = 10 Jahre), legal_hold (Boolean)
- Legal-Hold sperrt Löschung auch nach Retention-Ende
- AuditExportJob: tenant_id, requested_by, date_from/to, status, download_url (Scaleway Storage)
- Export: komprimiertes NDJSON oder CSV in Scaleway Object Storage
- Cron-Job für auto-Löschung nach Retention
REQ-audit-permissions
Audit-Zugriff permission-gegated.
Acceptance criteria:
- audit.read: Tenant-Admin kann eigene Audit-Einträge lesen
- audit.export: Tenant-Admin kann Export anfordern
- audit_event-Typ in Activity-Stream: nur sichtbar mit audit.read (M01 Block E)
- Plattform-Admin: sieht plattformweite Einträge (tenantId=null) über AdminAuditLog-View
Modul 22 — Notifications
source: _bmad-output/specs/M22-notifications.md
REQ-notification-datenmodell
Notification, NotificationPreference, NotificationDevice, NotificationBundle, NotificationQuietHours.
Acceptance criteria:
- Notification: tenant_id, recipient_user_id, category, template, payload (JSONB), channels_sent[], status, read_at, created_at
- NotificationPreference: user_id, category, in_app_enabled, email_enabled, push_enabled
- NotificationDevice: user_id, device_token, platform (ios|android), last_seen_at
- NotificationBundle: Anti-Spam-Bündelung: gleichartige Notifications innerhalb X Minuten zu einer Zusammenfassung
- NotificationQuietHours: user_id, start_time, end_time, timezone, days_of_week[]
REQ-notification-versand-pipeline
Drei-Kanal-Versand (In-App via SSE, Email via Provider, Mobile-Push via FCM/APNs) über BullMQ.
Acceptance criteria:
- notify()-Aufruf aus @hivegrid/notifications: immer via Service, nie direkter Email/Push-Versand aus Modul (INTEGRATION-CONTRACTS §7)
- Service entscheidet Kanal anhand NotificationPreference + QuietHours
- In-App: SSE-Stream (AD-9); Push: FCM (Android) + APNs (iOS); Email: via Provider (AD-6-pending)
- Novu als Notification-Middleware oder eigene BullMQ-Pipeline (Design-Entscheidung offen)
Modul 23 — Files
source: _bmad-output/specs/M23-files.md
REQ-files-datenmodell
File, FileVersion, FileChunk, FileUploadProgress, FileEntityLink.
Acceptance criteria:
- File: tenant_id, storage_key (Scaleway S3), filename, mime_type, size_bytes, uploaded_by_user_id, preview_url
- FileVersion: file_id, version_number, storage_key, size_bytes, created_at
- FileChunk: Chunked-Upload-State (für Dateien >5MB)
- FileEntityLink: file_id, entity_type, entity_id (polymorphe Verknüpfung)
- S3-Pfad: tenants/{tenant_id}/files/{file_id}/{version}/ (AD-1 RLS auf Storage)
REQ-files-upload-preview
Chunked-Upload, Preview-Generierung, Versionierung.
Acceptance criteria:
- Chunked-Upload via Resumable-Upload-API (TUS-Protokoll oder eigene Implementierung)
- Preview: PDF → PNG-Thumbnail; Bilder → WebP-Resize; Andere → Generic-Icon
- Versionierung: neue Version ersetzt nicht die alte (immer als FileVersion gespeichert)
- Customer-Portal-Upload: Endkunden können über M15 Dateien hochladen (im Tenant-Prefix)
Modul 24 — Globale Suche
source: _bmad-output/specs/M24-globale-suche.md
REQ-suche-datenmodell
SearchIndexEntry, RecentSearch, EmbeddingProviderJob.
Acceptance criteria:
- SearchIndexEntry: tenant_id, entity_type, entity_id, searchable_text, embedding (vector(1024)), last_indexed_at
- RecentSearch: user_id, query, entity_type, selected_entity_id, created_at (letzten 10)
- Outbox-Pattern: Embed-Job nach Entity-Mutation in Queue
REQ-suche-hybrid
Hybrid-Suche: Postgres-FTS + pgvector-Embeddings via RRF-Fusion (AD-5).
Acceptance criteria:
- Keyword: tsvector + GIN-Index auf searchable_text (Postgres-FTS)
- Semantisch: pgvector cosine similarity auf embedding-Spalte
- RRF (Reciprocal Rank Fusion) kombiniert beide Ergebnislisten
- Permission-aware: SearchAdapter filtert nach User-Permissions vor Rückgabe
- SearchAdapter-Interface: jedes Modul registriert Entitäten via indexed-entities.ts in packages/search/ (AD-10, INTEGRATION-CONTRACTS §8)
REQ-suche-ui
Cmd+K-Modal und Vollbild-Such-View.
Acceptance criteria:
- Cmd+K öffnet Modal überall in der App (global Hotkey)
- Debounced (300ms), min. 2 Zeichen
- Vollbild-Such-View: persistierte Suche, Filter, Ergebnis-Seiten
- RecentSearch angezeigt bei leerer Query
Modul 25 — Calendar-Sync
source: _bmad-output/specs/M25-calendar-sync.md
REQ-kalender-datenmodell
CalendarConnection, CalendarEvent, CalendarEventMapping, CalendarSyncCursor, CalendarWebhookEvent.
Acceptance criteria:
- CalendarConnection: user_id, provider (google|microsoft), oauth_tokens (verschlüsselt AD-8), status
- CalendarEvent: connection_id, provider_event_id, title, start_at, end_at, is_busy, is_all_day, ical_uid
- CalendarEventMapping: hg_entity_type, hg_entity_id, calendar_event_id (bidirektionale Verknüpfung)
- CalendarSyncCursor: last_sync_token / delta_link pro Connection
REQ-kalender-sync-adapter
Bidirektionaler Sync über CalendarAdapter-Interface.
Acceptance criteria:
- CalendarAdapter-Interface: connect(), syncFull(), syncDelta(), createEvent(), updateEvent(), deleteEvent()
- GoogleCalendarAdapter + OutlookAdapter implementieren Interface
- OAuth-Token-Refresh automatisch
- Webhook-Subscriptions für Push-Updates (Google Push Notifications, Outlook Subscriptions)
- HiveGrid-seitige Änderungen (Appointment via M06): Event in verbundenem Kalender anlegen
Modul 26 — Tasks
source: _bmad-output/specs/M26-tasks.md
REQ-tasks-datenmodell
Task, TaskWatcher.
Acceptance criteria:
- Task: id, tenant_id, title (Pflicht), description, status (open|in_progress|completed|cancelled), priority (low|medium|high|urgent), due_date, assigned_to_user_id, created_by_user_id, entity_type, entity_id (nullable — Verknüpfung), completed_at, archived_at, reminder_at
- TaskWatcher: task_id, user_id (follow-Funktion)
- Entity-Verknüpfung: Task kann mit Contact, Company, Lead, Deal, Project, Group verknüpft sein
REQ-tasks-reminder-archivierung
Reminder-System und Auto-Archivierung abgeschlossener Tasks.
Acceptance criteria:
- Reminder: M22-Notification bei due_date - X; konfigurierbar (15min, 1h, 1d vor Fälligkeit)
- Auto-Archivierung: abgeschlossene Tasks nach 30 Tagen (Cron-Job)
- Erstellungs-Quellen: manuell, Form-Action (M05), Automation-Action (M17), Chat-Shortcut (M13)
Modul 27 — Auth / Multi-Tenancy / Permissions
source: _bmad-output/specs/M27-auth-multi-tenancy.md
REQ-auth-multi-tenancy
Self-Service-Signup, Tenant-Slug, URL-Struktur (app.hivegrid.de, admin.hivegrid.de).
Acceptance criteria:
- Signup: Firmennamen → auto-generierter Slug (Umlaute transkribiert, lowercase, Bindestrich); User darf editieren; Live-Validierung auf Eindeutigkeit
- Slug nach Anlage unveränderlich (nur Plattform-Admin-Migrationstool)
- Reserved Words: admin, app, api, www, help, support, marketing, dev, test, signup, login, auth, static, assets, public, settings, portal, buch, f
REQ-auth-methoden
Email+Passwort, TOTP (2FA), Magic-Link für Customer-Portal.
Acceptance criteria:
- NIST-konformes Passwort (min 8 Zeichen, max 128, keine Komplexitäts-Erzwingung, Breach-Check via Pwned-Passwords)
- TOTP: RFC 6238, TOTP-Secret gespeichert verschlüsselt (AD-8), Backup-Codes
- Magic-Link: nur für Customer-Portal (M15), verboten für Mandanten-App-Login und Admin (AD-3)
- Auto-Logout: bei Passwort-/2FA-/Email-Änderung alle Sessions revoken (AD-4)
REQ-auth-rbac
Rollen-basiertes Permission-System mit Bundles und Tenant-Admin-Verwaltung.
Acceptance criteria:
- Role: id, tenant_id, name, is_system (nicht editierbar), permissions[] (JSON-Array)
- User ↔ Role: M:N (User kann mehrere Rollen haben)
- Permission-Keys in packages/entitlements/src/permissions.ts (INTEGRATION-CONTRACTS §10)
- SHK-Template: 6 Standard-Rollen geseedet (Partner-Liste 19.06.: Geschäftsführer, Projektleiter, Verwaltung, Vertriebler, Kundensupporter, Monteur)
- Permission-Check: server-side middleware + client-side hide (niemals nur client-side)
REQ-auth-user-lifecycle
User-Einladung, Onboarding, Deaktivierung, DSGVO-Löschung.
Acceptance criteria:
- Einladung: Token per Email (48h gültig), User setzt Passwort bei Annahme
- Deaktivierung: Sessions revoken, User nicht löschbar wenn Daten vorhanden (Soft-Deactivation)
- DSGVO-Löschung: User-PII anonymisiert, nicht hard-deleted wenn Audit-Trail vorhanden
REQ-auth-api-keys
API-Key-System für technische Integrationen.
Acceptance criteria:
- ApiKey: tenant_id, key_hash (SHA-256), name, scopes[], last_used_at, expires_at
- Key wird einmalig bei Erstellung angezeigt (danach nur Hash)
- Scopes: fein-granular analog Permission-System
- Rate-Limit: 1000 Req/Min (Default, konfigurierbar)
Modul 28 — Subscriptions/Billing
source: _bmad-output/specs/M28-subscriptions-billing.md
REQ-billing-datenmodell
TenantSubscription, SubscriptionProduct, SubscriptionPrice, SubscriptionFeature, TenantSubscriptionUsageRecord, Credit.
Acceptance criteria:
- TenantSubscription: tenant_id, legacyProvider_customer_id, legacyProvider_subscription_id, product_id, status (active|trialing|frozen|cancelled), trial_ends_at, current_period_start/end, seat_count
- Legacy-Provider-Webhook-Verarbeitung: checkout.session.completed, invoice.payment_succeeded, invoice.payment_failed, customer.subscription.deleted
- Frozen-Modus: Zugriff eingeschränkt (Read-Only-Middleware), Warnungen in App
- AI-Credits: Credit-Konto pro Tenant, verknüpft mit Subscription-Plan
REQ-billing-trial-dunning
Trial-Phase, Dunning-Workflow, Setup-Fee.
Acceptance criteria:
- Trial: 14 Tage Default, keine Kreditkarte erforderlich
- Dunning: bei fehlgeschlagener Zahlung → Email-Sequenz (Tag 1, 3, 7), dann Frozen-Modus
- Setup-Fee: einmalige Gebühr bei Enterprise-Buchung (Payment-Checkout-Session)
- Preise selbst geparkt (AD-15); Engine muss aber bereit sein
Modul 29 — Onboarding
source: _bmad-output/specs/M29-onboarding.md
REQ-onboarding-wizard
Branchen-getriebener Onboarding-Wizard nach Self-Service-Signup.
Acceptance criteria:
- OnboardingSession: tenant_id, current_step_id, completed_at, filter_answers (JSONB)
- Wizard-Schritte: Branche bestätigen → Teamgröße → Feature-Auswahl → Demo-Daten? → Einladungen
- SHK-Template: vorausgewählt wenn Branche = SHK
- OnboardingFilter: Branchen-spezifische Zweige im Wizard
REQ-onboarding-demo-daten
Demo-Daten-Provisioning auf Wunsch beim Onboarding.
Acceptance criteria:
- OnboardingDemoProvisioning: tenant_id, status (pending|running|completed|failed)
- Demo-Daten: 5 Beispiel-Contacts, 3 Deals, 2 Projekte, Form-Submission, Tasks
- Lösch-Funktion: Demo-Daten komplett entfernbar (Bulk-Delete per Flag is_demo_data=true)
- KI-Walkthrough optional nach Onboarding (AD-16)
Modul 30 — i18n
source: _bmad-output/specs/M30-i18n.md
REQ-i18n-architektur
Locale-File-Struktur, Language-Resolution, Build-Validierung.
Acceptance criteria:
- Locale-Files: packages/i18n/src/locales/{lang}/{modul}.json (INTEGRATION-CONTRACTS §9)
- Naming: {modul}.{bereich}.{key} (z.B. sales.kanban.empty_state)
- Language-Resolution: User-Preference → Tenant-Default → de (Fallback)
- ESLint-Rule blockt JSX-Text-Nodes ohne t(); Build-Lint blockt Hard-Strings
- ICU-Pluralization: {count, plural, one {# Datei} other {# Dateien}}
- DeepL-Pipeline für automatische Übersetzungs-Vorschläge (Phase 2)
REQ-i18n-outbound
Sprachauswahl für Outbound-Kommunikation (Email, Push, WhatsApp).
Acceptance criteria:
- Contact.language (DE/EN, Default DE) steuert Sprache der automatischen Kommunikation
- Notification-Templates in DE + EN Pflicht für Phase 1
- M22 notify()-Aufruf übergibt context_language; Service wählt Template
Modul 31 — Branding
source: _bmad-output/specs/M31-branding.md
REQ-branding-theme-phase1
User-Level Theme-Preference (Light/Dark/System) in Phase 1.
Acceptance criteria:
- User.theme_preference (light|dark|system, Default system)
- Cookie für SSR-Kompatibilität (kein Flash of wrong theme)
- CSS-Variablen für Theme-Switching
REQ-branding-tenant-phase2
Tenant-Branding, White-Label, Custom-Domain (Phase 2).
Acceptance criteria:
- TenantBranding: logo_url, primary_color, secondary_color, custom_domain
- Feature-Gate: branding.white_label (nur in Enterprise-Plan)
- Email-Templates mit Tenant-Logo
- Capacitor-App-Theming (AD-17, Mobile-App)
Modul 32 — Feature-Flags
source: _bmad-output/specs/M32-feature-flags.md
REQ-feature-flags-system
Platform-Admin-Feature-Flag-System für per-Tenant-Aktivierung.
Acceptance criteria:
- FeatureFlag: key (unique), name, description, default_value (Boolean), type (boolean|percentage|json)
- TenantFeatureFlag: tenant_id, flag_key, value, activated_at, activated_by_admin_id
- FeatureFlagFilter: Regeln für automatische Aktivierung (Branche, Teamgröße, Plan)
- tenantHasFlag(tenantId, flagKey): Helper-Funktion; gecacht in Redis (TTL 5 Min)
- Änderungen geloggt in AdminAuditLog (M37)
Modul 33a — Apps-Engine
source: _bmad-output/specs/M33a-apps-engine.md
REQ-apps-engine-datenmodell
DataConnection, AppSyncRun, AppSyncRunLog, AppSyncItem, Adapter-Registry.
Acceptance criteria:
- DataConnection: tenant_id, app_key (gmail|outlook|aircall|kwp|legacyProvider|pandadoc|...), status (connected|disconnected|error), credentials_encrypted (AD-8), config (JSONB), last_synced_at
- AppSyncRun: connection_id, status (running|completed|failed), started_at, finished_at, items_processed
- AppSyncItem: run_id, external_id, action (create|update|delete), payload_hash, status
- Adapter-Registry: app_key → Adapter-Klasse (type-safe Registry)
REQ-apps-engine-lifecycle
App-Connect-Flow, Sync-Mechanik, Connection-Health-Monitoring.
Acceptance criteria:
- OAuth2-Connect-Flow für Gmail, Outlook, AirCall, PandaDoc
- API-Key-Connect für KWP (type=windows_client), Legacy-Provider
- Sync-Intervalle: konfiguierbar per App (Push-Webhook bevorzugt, Pull als Fallback)
- Connection-Health: Heartbeat-Check, Auto-Reconnect-Versuch, Tenant-Admin-Alert bei Fehler
- Settings-UI: /settings/integrationen/{app_key}; Einstiegspunkt für alle Integrations
Modul 34 — Public API & Webhooks
source: _bmad-output/specs/M34-public-api.md
REQ-public-api-read
Phase-1 Read-Only REST-API für Contacts, Deals, Leads, Projects, Tasks, Companies.
Acceptance criteria:
- Endpoints: GET /api/v1/contacts, /deals, /leads, /projects, /tasks, /companies (je List + Detail)
- Auth: API-Key (Bearer), Permission-Scoped (M27 API-Keys)
- Rate-Limit: 1000 Req/Min Default (Redis-backed)
- OpenAPI-Spec: automatisch generiert (z.B. via @asteasolutions/zod-to-openapi)
- IntegrationApiRequest: Logging aller API-Zugriffe für Audit + Rate-Limit
REQ-public-webhooks
Incoming Lead-Push Webhooks + Outgoing Webhook-Subscriptions.
Acceptance criteria:
- IncomingWebhookIngestion: tenant_id, source_key, payload, processed_at; Lead aus Payload anlegen
- WebhookSubscription: tenant_id, event_type (deal.won, lead.created, ...), target_url, secret, active
- WebhookDelivery + WebhookDeliveryAttempt: Retry-Logik (exponentielles Backoff, max 5 Versuche)
- Signatur-Validierung: HMAC-SHA256 im X-HiveGrid-Signature-Header
Modul 35 — DSGVO-Export / Account-Löschung
source: _bmad-output/specs/M35-dsgvo-export.md
REQ-dsgvo-export
GDPR-Daten-Export als ZIP via BullMQ-Worker.
Acceptance criteria:
- GdprExportJob: user_id, tenant_id, requested_at, status (pending|running|completed|failed), download_url (Scaleway, 72h signed URL)
- Export-Inhalt: alle personenbezogenen Daten des Users (Profile, Activities, Chat-Messages, Files-Metadata, Custom-Field-Values, Audit-Trail-Auszug)
- ZIP + NDJSON-Format
- Download-Link-Email via M22
REQ-dsgvo-tenant-deletion
Tenant-Account-Löschung mit Crypto-Shredding.
Acceptance criteria:
- TenantDeletionRequest: tenant_id, requested_by_user_id, reason, scheduled_for (14-Tage-Frist)
- Crypto-Shredding: Per-Tenant-DEK löschen → alle verschlüsselten Daten unlesbar (AD-8)
- Legacy-Provider-Subscription canceln vor Löschung
- pgvector-Embeddings, Redis-Cache, Scaleway-Storage-Objekte alle entfernen
- AvvAcceptance + Subprocessor-Liste in Privacy-Hub-Route anzeigbar
Modul 36 — Mobile-App
source: _bmad-output/specs/M36-mobile-app.md
REQ-mobile-capacitor
Capacitor-Wrapper für iOS/Android mit nativem Zugriff auf Kamera, Biometrie, Push.
Acceptance criteria:
- Capacitor 6.x, iOS ≥ 16, Android ≥ 10
- Face-ID / Touch-ID / Fingerprint für App-Lock (zusätzlich zur Session)
- Kamera für Foto-Upload + QR-Code-Scan (Bauteil-Scan Phase 2)
- Deeplinks: hivegrid://... → App-Route-Mapping
- Privacy-Manifest (Apple): NSCameraUsageDescription, NSFaceIDUsageDescription u.a.
REQ-mobile-offline-sync
Voller Offline-Betrieb mit IndexedDB + Sync-Queue (AD-17).
Acceptance criteria:
- OfflineSyncQueue: queued_at, entity_type, operation (create|update|delete), payload, synced_at, conflict_resolution
- IndexedDB: lokale Kopie von aktuellen Aufträgen, Kontakten, Tasks (Subset)
- Conflict-Resolution: "KWP gewinnt" bei KWP-Sync-Konflikten; "Last-Write-Wins" für HiveGrid-interne Konflikte
- Service-Worker für Asset-Caching
- Offline-Indikatoren (Klartext: "Du arbeitest offline — Änderungen werden synchronisiert sobald Verbindung besteht")
REQ-mobile-push
Push-Notifications über APNs (iOS) und FCM (Android).
Acceptance criteria:
- NotificationDevice: registration_token, platform, user_id, tenant_id, last_seen_at
- Token-Rotation bei App-Neustart
- M22 notify()-Aufruf → Push-Kanal wenn NotificationDevice registriert
- Foreground/Background-Handling unterschiedlich
Modul 37 — Plattform-Admin
source: _bmad-output/specs/M37-plattform-admin.md
REQ-plattform-admin-identität
Getrennte AdminUser-Welt (AD-3) auf admin.hivegrid.de.
Acceptance criteria:
- AdminUser: id, email, password_hash, totp_secret (verschlüsselt AD-8), status (active|suspended), roles[]
- AdminSession: session_id, admin_user_id, ip_address, user_agent, created_at, last_active_at, expires_at; server-side in Postgres (AD-4)
- AdminRole + AdminPermission: RBAC für Plattform-Admin-Aktionen
- Magic-Link verboten (AD-3)
- IP-Binding der Session
REQ-plattform-admin-features
Tenant-Management, Subscription-Verwaltung, Feature-Flags, Worker-Queue-Monitoring.
Acceptance criteria:
- Tenant-Liste + Detail: Subscription-Status, Last-Login, Feature-Flags, Admin-Notes (AdminTenantNote)
- Subscription: manuelle Overrides, Trial-Verlängerung, Plan-Wechsel
- Feature-Flags verwalten (M32-Integration)
- Worker-Queue-Monitoring: BullMQ-Queue-Status, failed Jobs, Retry
- Support-Inbox: AdminSupportTicket aus M39 Feedback-Widget
- Admin-Lead-Management: Interesse-Anfragen für Sales-Pipeline der HiveGrid GmbH selbst
Modul 38 — Help-Center (öffentlich)
source: _bmad-output/specs/M38-help-center.md
REQ-help-center
Öffentliches file-basiertes Markdown-Help-Center mit Suche und SEO.
Acceptance criteria:
- Markdown-Files in content/help/{lang}/{category}/{slug}.md
- Kategorien + Artikel-Index bei Build generiert
- Suche: FlexSearch (client-side für Phase 1), Postgres-FTS als Fallback-Server-Route
- Deep-Links: aus App heraus per Artikel-Key verlinkbar
- SEO: SSR-gerenderter HTML, OG-Meta-Tags, sitemap.xml
- Routen: /help/{lang}/{category}/{slug} (INTEGRATION-CONTRACTS §3)
Modul 39 — Help-Desk / Support
source: _bmad-output/specs/M39-help-desk.md
REQ-feedback-widget
In-App Feedback-Widget + Platform-Admin-Support-Inbox.
Acceptance criteria:
- Feedback: tenant_id, user_id, category (bug|feature|question|other), message, screenshot_url, page_url, created_at
- Rate-Limit: max 10 Submissions pro User pro Stunde
- Attachments: file_ids[] (via M23)
- Activity-Log: jeder Feedback-Status-Wechsel geloggt
- AdminSupportTicket in M37: Plattform-Admin sieht alle Feedbacks als Support-Queue
- Audit-Trail für Support-Team-Aktionen
INTEGRATION-CONTRACTS — Querschnitt
source: docs/INTEGRATION-CONTRACTS.md
REQ-integration-sidebar
Alle neuen Modul-Bereiche müssen in der Sidebar-Konfiguration registriert sein.
Acceptance criteria:
- Registrierung in apps/web/app/application/sidebar/ (AD-10, nicht packages/ui-hivegrid/sidebar.config.ts)
- SidebarEntry: id (kebab-case), group (eine der 6), label (i18n-Key), icon (lucide-react), route, permission, badge?, order, feature_flag?
- Neue Funktion ohne Sidebar-Eintrag: nicht akzeptiert
REQ-integration-routes
Verbindliche URL-Schemata (INTEGRATION-CONTRACTS §3).
Acceptance criteria:
- Mandanten-App: app.hivegrid.de/{modul}/... (Tenant aus Session/Subdomain, NICHT im Pfad)
- 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: api.hivegrid.de/v1/{resource}
- MCP-Server: mcp.hivegrid.de
REQ-integration-activity-wiring
Jede schreibende Aktion mit Entitäts-Bezug muss logActivity() aufrufen.
Acceptance criteria:
- logActivity() aus @hivegrid/activity (INTEGRATION-CONTRACTS §5)
- Signatur: {tenantId, actorId, actorType, entityType, entityId, type, payload}
- Trennung: logActivity() ist NICHT der Audit-Eintrag (Audit läuft über Prisma-Middleware separat)
REQ-integration-audit-wiring
Audit ist automatisch via Prisma-Middleware; Ausnahmen manuell.
Acceptance criteria:
- Prisma-Middleware in M21 generiert AuditEntry für alle write-Operationen automatisch
- Ausnahmen (S3-Upload, externe Webhooks): manuell über auditEvent() aus @hivegrid/audit
- Keine manuelle Audit-Implementierung in Modul-Code nötig (Verantwortung bei M21-Middleware)
REQ-integration-notification-wiring
Benachrichtigungen immer über notify(), nie direkter Kanal-Zugriff.
Acceptance criteria:
- notify() aus @hivegrid/notifications (INTEGRATION-CONTRACTS §7)
- Signatur: {tenantId, recipientId, category, template, payload, priority}
- Service (M22) entscheidet Kanal + Bündelung + Ruhezeiten
REQ-integration-view-model-pflicht
Jede Route muss im Loader ein View-Model bauen.
Acceptance criteria:
- Loader in app/routes/** gibt View-Model zurück
- UI-Components in packages/ui-app/** empfangen NUR VM + Action-Callbacks
- Kein direkter Store/DB-Zugriff in UI-Components
REQ-integration-smoke-tests
Jede neue Route bekommt einen Smoke-Test.
Acceptance criteria:
- Smoke-Test in e2e/smoke/{modul}.spec.ts
- Smoke-Tests laufen gegen packages/ui-mock (Hot-Swap-Architektur)
- Schlagen Smoke-Tests mit ui-mock fehl → Hot-Swap-Architektur verletzt