11 KiB
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 |
|
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_idname,description(Markdown)slug(URL-Pfad-Bestandteil, unique pro Tenant)subtype(standard | acceptance_form | onboarding | survey)status(draft | published | archived)published_at,archived_atis_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,positionfield_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)placeholderconditional_visibility(JSON — Phase 2)
FormSubmission
id,tenant_id,form_id,submitted_atsubmitter_user_id(nullable)submitter_email,submitter_phonesubmitter_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)
FormLink
id,form_id,tokencreated_by_user_id,created_atexpires_at(optional)usage_count,usage_limit(optional)purpose(Freitext)
FormsTag / FormTag
- Standard-Tag-System (analog M1)
FormAction
id,form_id,positionaction_type(Enum — siehe Block H)action_config(JSON)enabledruns_on(submission | submission_with_filter)filter_rules(JSON)
FormActionLog
id,submission_id,action_idexecuted_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:
requiredmin_length,max_lengthmin_value,max_valueregex_patternaccepted_file_types[],max_file_size_mbcustom_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.
Personalisierte Links
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)