379 lines
11 KiB
Markdown
379 lines
11 KiB
Markdown
---
|
||
module: 5
|
||
title: Form Builder
|
||
phase: 1
|
||
status: detail-spec-draft
|
||
last_updated: 2026-05-08
|
||
session_source: brainstorming-session-2026-05-07-2206.md
|
||
related_lps: [LP-3, LP-9, LP-10]
|
||
spec_style: requirements-pur
|
||
size: 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)
|
||
|
||
### FormLink
|
||
- `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`.
|
||
|
||
### 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)
|