Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/_bmad-output/specs/M05-form-builder.md
T

11 KiB
Raw Blame History

module, title, phase, status, last_updated, session_source, related_lps, spec_style, size
module title phase status last_updated session_source related_lps spec_style size
5 Form Builder 1 detail-spec-draft 2026-05-08 brainstorming-session-2026-05-07-2206.md
LP-3
LP-9
LP-10
requirements-pur XL

Modul 5 — Form Builder

Detail-Spec gemäß LP-9. XL-Modul. Voll Google-Forms-Niveau zu Phase 1 (User-Entscheidung). Klebstoff zwischen externer Welt und HiveGrid. Basis: alte Codebase + Brainstorming-Ergänzungen.

Themenblöcke

A. Datenmodell
B. Form-Editor (Drag-&-Drop)
C. Feldtypen
D. Validation-Regeln
E. Sharing & Embed
F. Form-Templates (SHK)
G. Submissions-Verwaltung
H. Form-Actions (bei Submit)
I. Integration mit anderen Modulen
J. Permissions
K. Phase 2 (Verzweigungslogik, Charts, etc.)

Block A — Datenmodell

Form                  — Form-Definition pro Tenant
FormField             — Feld innerhalb eines Forms
FormSubmission        — eine Antwort/Einreichung
FormSubmissionAnswer  — pro Feld pro Submission der Antwort-Wert
FormFile              — Datei-Upload aus Submission
FormLink              — Sharing-Link mit Token
FormsTag / FormTag    — Tag-System
FormAction            — was passiert bei Submit
FormActionLog         — Ausführungs-Log pro Action
FormLog               — generelles Audit-Log pro Form

Form

  • id, tenant_id, created_at, updated_at, created_by_user_id
  • name, description (Markdown)
  • slug (URL-Pfad-Bestandteil, unique pro Tenant)
  • subtype (standard | acceptance_form | onboarding | survey)
  • status (draft | published | archived)
  • published_at, archived_at
  • is_public (über öffentliche URL einsehbar?)
  • requires_login (User-Login Pflicht — Customer-Portal-User reicht)
  • submission_limit (optional — max. Anzahl Submissions)
  • submission_close_at (optional — Auto-Schließung)
  • success_message (Markdown)
  • redirect_url (optional)

FormField

  • id, form_id, position
  • field_key (snake_case, unique pro Form)
  • label, description (Hilfetext)
  • field_type (Enum — siehe Block C)
  • field_config (JSON — typ-spezifisch)
  • required (Boolean)
  • validation_rules (JSON — siehe Block D)
  • default_value (JSON)
  • placeholder
  • conditional_visibility (JSON — Phase 2)

FormSubmission

  • id, tenant_id, form_id, submitted_at
  • submitter_user_id (nullable)
  • submitter_email, submitter_phone
  • submitter_ip, submitter_user_agent (Audit)
  • submission_data (JSON — alle Antworten)
  • linked_entity_type, linked_entity_id (z.B. → Deal-ID)
  • is_complete (Phase 2 für Multi-Step Save-and-Continue)
  • archived_at

FormFile

  • id, submission_id, field_key, file_id (FK auf M23 File)
  • id, form_id, token
  • created_by_user_id, created_at
  • expires_at (optional)
  • usage_count, usage_limit (optional)
  • purpose (Freitext)

FormsTag / FormTag

  • Standard-Tag-System (analog M1)

FormAction

  • id, form_id, position
  • action_type (Enum — siehe Block H)
  • action_config (JSON)
  • enabled
  • runs_on (submission | submission_with_filter)
  • filter_rules (JSON)

FormActionLog

  • id, submission_id, action_id
  • executed_at, status (success | failed | skipped)
  • result (JSON), error_text

FormLog

  • id, form_id, event_type, event_data, created_at, created_by_user_id
  • Audit für Form-Änderungen

Block B — Form-Editor

Editor (/{tenant}/forms/:id/edit)

Zu zeigende Daten:

  • Form-Stammdaten
  • Liste aller Felder in Reihenfolge
  • Live-Vorschau
  • Validation-Hinweise

Benötigte UI-Elemente:

  • Sektion für Stammdaten
  • Drag-&-Drop-Liste der Felder
  • Add-Field-Funktion mit Feldtyp-Picker
  • Pro Feld: Edit / Duplizieren / Löschen / Sortieren
  • Live-Vorschau-Pane
  • Save + Publish-Funktion
  • Sharing-Funktion (Link-Generator)
  • Embed-Code-Generator
  • Versionierung (Phase 2)

Operationen:

  • Stammdaten editieren
  • Feld hinzufügen / löschen / duplizieren / verschieben
  • Feld-Konfiguration editieren
  • Validation pro Feld setzen
  • Form publishen / unpublishen
  • Form duplizieren (als Vorlage)
  • Form archivieren

Klartext-Validation:

  • Feld ohne Label: „Feld 3 hat keinen Label — bitte ausfüllen."
  • Slug-Konflikt: „Slug ‚kontakt' wird bereits von einem anderen Form genutzt."
  • Required ohne Validation: „Feld ‚Email' ist required, aber keine Validation gesetzt — Email-Format-Validation hinzufügen?"

Block C — Feldtypen (Phase 1)

Feldtyp Anwendung
text Single-Line Text
textarea Multi-Line Text
number Integer / Decimal
date / datetime / time Datums-/Zeit-Eingaben
select Single-Select Dropdown
multiselect Multi-Select Chips
boolean Checkbox / Toggle
email Auto-Format-Validation
url Auto-Format-Validation
phone E.164-Normalisierung
file Beliebige Datei-Upload
photo Foto-Upload mit Mobile-Kamera-Direktzugriff
signature Touch-Signatur-Komponente
address Auto-Complete (Maps-Adapter M25)
section_header Anzeige-Element
description_block Markdown-Anzeige
hidden Vorausgefüllt aus URL-Params

Phase 2: repeater, multi_step, conditional_visibility.


Block D — Validation-Regeln

Pro Feld:

  • required
  • min_length, max_length
  • min_value, max_value
  • regex_pattern
  • accepted_file_types[], max_file_size_mb
  • custom_error_message

Phase 2: Cross-Field-Validation.


Block E — Sharing & Embed

Public URL

app.hivegrid.de/f/{tenant_slug}/{form_slug} — wenn is_public=true.

  • app.hivegrid.de/f/{tenant_slug}/{form_slug}/?token={token} mit FormLink
  • Tracking, optional usage_limit, expires_at

iFrame-Embed

  • Embed-Code-Generator
  • Auto-Resize-JS

JS-Snippet (Inline)

  • Direkt in externe Website embeddet
  • CORS-konform via app.hivegrid.de/embed.js

QR-Code

  • Generator für Print-Material (PNG/SVG)

Block F — Form-Templates (SHK-Branchen-Template)

Beim Tenant-Anlegen geseedet:

Template Subtype Zweck
„Kontakt-Anfrage" standard Lead-Kontaktformular für Website
„Sales-Aufnahme Vor-Ort" standard Vertriebler nimmt vor Ort technische Daten auf
„Foto-Checkliste" standard Monteur dokumentiert Bestandsanlage
„Acceptance-Protokoll Anlage" acceptance_form siehe M4 SHK-Default
„Wartungs-Buchung" standard Endkunde bucht Wartungstermin
„Krankmeldung" standard Mitarbeiter-Form (M14)
„Urlaubsantrag" standard Mitarbeiter-Form (M14)
„Customer-Feedback-Survey" survey Nach Acceptance an Kunde

Templates deklarativ (LP-3 + AV #3).


Block G — Submissions-Verwaltung

Liste (/{tenant}/forms/:id/submissions)

Zu zeigende Daten:

  • Submitter (Email/Phone)
  • Submission-Datum
  • Verlinkte Entität
  • Status der Action-Ausführungen
  • Ausgewählte Feld-Werte als Spalten

Benötigte UI-Elemente:

  • Tabellarische Anzeige
  • Filter nach Datum / Entität / Submitter
  • Spalten-Konfiguration
  • Bulk-Auswahl
  • Export als CSV
  • Klick öffnet Detail

Detail (/{tenant}/forms/:id/submissions/:submission_id)

Zu zeigende Daten:

  • Alle Antworten in Form-Reihenfolge
  • Submitter-Metadata (IP, User-Agent, Datum)
  • Ausgeführte Form-Actions mit Status + Klartext
  • Verknüpfte Entitäten
  • File-Uploads als Vorschau

Operationen:

  • Action erneut ausführen (Re-Run)
  • Manuell Entitäten verknüpfen
  • Submission archivieren / löschen (DSGVO)
  • PDF-Export der Submission

Block H — Form-Actions (bei Submit)

Pro Form mehrere Actions in Reihenfolge:

Action Zweck
send_email_to_submitter Bestätigung an Submitter
send_email_to_team Email an interne Empfänger
create_lead Lead in Lead-Inbox (M2)
create_contact Kontakt in CRM (M1)
create_deal Deal in Sales-Pipeline (M3) — mit Pipeline-Auswahl
create_project Project in Auftragspipeline (M4) — mit Pipeline-Auswahl
create_task Task (M26)
link_to_existing_entity Auto-Match über Email/Phone
webhook_send Externer Webhook
trigger_automation Automation-Engine triggern (M17)
kwp_push Daten an KWP (M19) — z.B. Acceptance-Daten

Field-Mapping: pro Action konfigurierbar (Form-Feld → Entitäts-Feld).

Conditional Actions: mit filter_rules nur bei bestimmten Inhalten.


Block I — Integration mit anderen Modulen

Modul Integration
M1 CRM Submission → Contact-Anlage; Auto-Match Email/Phone
M2 Lead-Inbox Submission → Lead-Anlage Standard-Workflow
M3 Sales-Pipeline create_deal-Action mit Pipeline-Targeting
M4 Projekte Sales-Aufnahme + Foto-Checklisten + Acceptance als ProjectForm
M9 Email Bestätigungs-Mails über Actions
M11 WhatsApp (P2) Bestätigung per WhatsApp
M17 Automation Trigger form.submitted; Actions können Automation triggern
M19 KWP Acceptance-Forms pushen Daten zu KWP
M22 Notifications Push/Email an Tenant-User bei neuer Submission
M23 Files File-/Photo-Uploads landen im Tenant-File-Storage
M24 Suche Forms + Submissions im Suchindex
M25 Calendar Address-Feld nutzt Maps-Adapter
M14 HR-Hub Krankmeldung/Urlaubsantrag-Forms

Block J — Permissions

Permission Erlaubt
forms.read_own Eigene Forms sehen
forms.read_all Alle Tenant-Forms sehen
forms.write Forms anlegen + bearbeiten
forms.publish Forms publishen / unpublishen
forms.delete Hard-Delete
forms.view_submissions Submissions einsehen
forms.export_submissions CSV-Export
forms.admin Voll-Verwaltung + Templates + Bulk-Operations

Bundle-Mapping

Bundle Atomare Permissions
forms.basic read_own + view_submissions
forms.builder obigen + read_all + write
forms.publisher obigen + publish + export_submissions
forms.admin alle

Default-Rollen-Zuweisung

Rolle Permission
GF forms.admin
Vertriebsleiter / PL forms.publisher
Marketing forms.publisher
Vertriebler / Büro forms.builder
Monteur forms.basic

Block K — Phase 2

  • Verzweigungslogik (conditional_visibility)
  • Multi-Step-Forms mit Save-and-Continue
  • Form-Charts / Statistik-View
  • Cross-Field-Validation
  • A/B-Testing
  • Repeater-Felder
  • Form-Templates-Marketplace (M33c)

Architektur-Vorschriften (Querschnitt)

  • LP-3, AV #3: SHK-Form-Templates Branchen-Template-Seeding
  • LP-10, AV #1: Klartext-Validation-Errors
  • AV #5: Permissions-aware-Default
  • AV #6: Audit-Trail (FormLog)

Detail-Spec-Status: DRAFT

Modul 5 komplett spec'd basierend auf alter Codebase.

Offene Detail-Punkte:

  • Drag-&-Drop-Library-Wahl (Boilerplate)
  • Anti-Spam für öffentliche Forms (Honeypot, hCaptcha — analog M27)
  • Versionierungs-Strategie (Phase 2)