Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/AK-P16c.md
T

16 KiB
Raw Blame History

AK-P16c · P16 Form-Builder (Editor + Submission + Actions)

Typ Dev (Code)
Owner Akeshan
Phase P16 — Kalender, Booking, Forms & Signatur
Cycle/Fenster W4 — USP, Härtung & Launch · fällig 2026-07-06 · Gate W4
Status Done (2026-07-11) · Subframe-UI vollständig integriert · Audit 2026-07-17: Action-Konfig-Regression aus PR #71 gefixt (Tab „Aktionen"), Forms-e2e ergänzt → 8/8 DoD

🎨 subframe-ui: integriert (Stand 2026-07-10) — der komplette WF-P16 Form Builder-Flow ist hinter der bestehenden Loader/Action-Grenze umgesetzt: S00 Verwalten (+E01/E02), S01 Formularart, S02 Fragen-Editor, S02L Lead-Zuweisung (+E05-Warnung), S03 Design, S05 Antworten (+E03/E04), S04 Public (+V01–V03). Rest-Delta (Soll-Elemente ohne Backend: Versionsverlauf, Theme-Logo/-Breite, Bereich/Datei/Pipeline-Lead-Mapping, Optionen-mischen) siehe „Noch offen".

Abhängigkeiten & Parallelität

  • Blocked by: AK-INFRA2 (mCaptcha + Rate-Limit-Infra für öffentliche Endpunkte), R-P7 (Lead-Inbox — Post-Submit-Action „Lead anlegen")
  • Blocks: — (Form-Renderer wird in AK-P16b Intake + AK-P17 HR-Anträge wiederverwendet)
  • Läuft parallel zu: Raffaels Kern-Kette + den anderen P16-Slices. Eigene prisma/schema/forms.prisma (AD-21); Post-Submit-Actions schreiben in CRM/Tasks/Automation. Sync-Punkt: R-P7 (Lead) für die create_lead-Action.
  • Konflikt-Risiko: gering — additive Tabellen; Fremd-Schemata nur über Actions/Relationen.

Was wir bauen

Einen Drag-&-Drop-Form-Builder auf Google-Forms-Niveau: 12 Feld-Typen, Conditional Logic („zeige Feld X wenn Y = Z"), Validierung pro Feld, geseedete SHK-Form-Templates und Live-Vorschau. Sharing über öffentliche URL + QR + iFrame (personalisierte Links / JS-Snippet → v2). Eingehende Submissions feuern Post-Submit-Actions mit Field-Mapping und ActionLog (Lead/Kontakt/Projekt/Task anlegen, Email an Submitter/Team, Webhook, Automation-Trigger, Auto-Match). Öffentliche Endpunkte sind Rate-Limit + mCaptcha + DSGVO-Pflicht abgesichert. Der Form-Renderer ist wiederverwendbar (Booking-Intake AK-P16b, HR-Anträge AK-P17).

Benötigte Screens (Backend bedient — Design liefert D-FORM + D-P16)

Screen [Route] Kern-Inhalt
Form-Builder-Canvas [/forms/:id/edit] Feld-Palette (12 Typen), Drag-&-Drop-Canvas, Feld-Konfiguration, Conditional-Logic-Editor, Live-Vorschau, Publish-Toggle, Sharing (URL/QR/iFrame), Post-Submit-Actions mit Field-Mapping — BESPOKE
Forms-Liste [/forms] Name/Subtyp/Status/Submissions-Anzahl/letzte Submission; SHK-Templates geseedet
🌐 Öffentliches Formular [/f/{tenant}/{slug}] Gerenderte Felder, Conditional Logic live, mCaptcha, Submit → Erfolgs-Text/Redirect, Tenant-Logo — BESPOKE-Public
Submissions [/forms/:id/submissions] Antwort-Tabelle (Spalten = Felder), Filter, CSV; Detail: alle Antworten, Submitter-Metadata, Action-Log mit Re-Run, File-/Foto-Vorschau, PDF-Export

Definition of Done

  • 12 Feld-Typen + Conditional Logic + Validierung pro Feld + geseedete SHK-Templates + Live-Vorschau
  • Embed: öffentliche URL + QR + iFrame (personalisierte Links / JS-Snippet → v2)
  • Post-Submit-Actions (Lead/Kontakt/Projekt/Task, Email, Webhook, Automation-Trigger, Auto-Match) mit Field-Mapping + ActionLog (Re-Run)
  • Rate-Limit + mCaptcha + DSGVO-Pflicht auf öffentlichen Endpunkten; Race-Schutz beim Submit
  • Form-Renderer als wiederverwendbare Komponente (Booking-Intake, HR-Anträge)
  • Permission-Bundle forms.* (basic/builder/publisher/admin) serverseitig Owner-gefiltert
  • Konnektor tenantHasModule('forms'); RLS auf allen Tenant-Tabellen
  • e2e-Smoke Forms (fehlender DoD-Punkt, Audit 2026-07-17): tests/e2e/forms.spec.ts (Login → /forms → Marker ui.forms.list; AGENTS.md D.19 — es gab keinen Forms-e2e)

Umsetzungs-Notiz

2026-07-01: AK-P16c umgesetzt auf Branch feat/AK-P16c-complete.

  • Form-Datenmodell in prisma/schema/formWidget.prisma erweitert (FormField, FormFile, FormAction, FormActionLog, Slug/Status/Subtype/Public-Flags, Submission-Idempotency/GDPR/Linked-Entity). Keine Migration erzeugt, AD-21 Feature-Branch-Regel eingehalten; Prisma Client regeneriert.
  • Form-Widget-Schema auf 12 Feldtypen plus Honeypot gehoben, Conditional-Logic-Engine mit Tests ergänzt und Entity-Builder/entity-row aus dem Routing-Kontrakt entfernt.
  • Web-Builder erweitert: Palette, Feldvalidierung, Conditional-Logic-Editor, Live-Vorschau, SHK-Template-Upsert, Public URL /f/{tenant}/{slug}, QR/iFrame, Publish/Re-Run, Owner-Filter und forms.* Permissions.
  • Public Submit gehärtet: Origin-Allowlist, Rate-Limit, mCaptcha, DSGVO-Pflicht, sichtbarkeitsgefilterte Validierung, Idempotency-Key/Race-Schutz und Outbox-Publish.
  • Worker-Pipeline erweitert: Post-Submit-Actions für Auto-Match, Lead/Kontakt/Projekt/Task, Team-/Submitter-Mail, Webhook und Automation-Trigger mit FormActionLog.
  • Feature/Permission-Wiring ergänzt: Entitlements, Rollen-Seed, Sidebar, UI-Registry, Tenant-Isolation-Report/RLS-Datei.

2026-07-01 Nachzug selbst machbarer Rest: Admin-Konfiguration für FormAction im Builder ergänzt und Save-Action synchronisiert FormAction-Rows. Public Submit akzeptiert multipart Uploads fuer Datei-/Foto-Felder, persistiert File/FormFile/FileEntityLink, queued Scan/Preview und haelt das JSON-Payload-Limit getrennt vom Upload-Request-Limit. Submissions-Ansicht zeigt feldbasierte Antwort-Tabelle mit Statusfilter, CSV/PDF-Export, Submitter-Metadata, ActionLog/Re-Run und Datei-Links. Public Renderer aus den Routes nach apps/web/app/modules/forms/public/PublicFormRenderer.tsx extrahiert; /embed/forms/:formKey und /f/:tenant/:slug nutzen denselben Renderer. Builder-Save synchronisiert FormField-Rows aus der Definition.

Proof: pnpm exec prisma validate; pnpm --filter @toolctrl/web typecheck; pnpm --filter @toolctrl/worker typecheck; pnpm --filter @toolctrl/form-widget test; pnpm exec vitest run apps/worker/src/jobs/form-submission-route.test.ts apps/worker/src/index.test.ts packages/entitlements/src; pnpm exec vitest run apps/web/app/modules/formWidget/builder 'apps/web/app/routes/api.embed.forms.$formKey.submit.test.ts' 'apps/web/app/routes/app.$tenant/forms.$id.defaults.test.ts' 'apps/web/app/routes/app.$tenant/forms.$id.action.test.ts' 'apps/web/app/routes/app.$tenant/forms.$id.i18n.test.ts'; pnpm lint.

Stand: 7/7 Dev-DoD grün = 100 % selbst machbarer Dev-Anteil. Ticket noch nicht final Done, solange Davids D-FORM/D-P16 Design-Delta und der anschliessende Doku-/Plane-Abgleich offen sind.

Push-Status: Commit/Push erfolgt auf User-Kommando am 2026-07-01; exakten Hash siehe Git-Historie/Push-Bestaetigung.

Plane: Kommentar 2d5037a5-5c59-4a07-9a53-8a597d9b6de4 am 2026-07-01 gesetzt. Ticket bewusst nicht auf Done gesetzt, weil Davids Design-Delta noch offen ist.

2026-07-09 Subframe-UI-Nachzug (teilweise): Die Forms-Verwaltung wurde aus dem handgeschriebenen Route-Markup in apps/web/app/components/screens/forms/FormsAdminPage.tsx gezogen und an Davids WF-D-FORM Form Builder / Subframe-Screen S00 Formulare verwalten angelehnt. Loader, Action, Permissions, Owner-Filter, Template-Seeding, Toggle/Delete und Embed-Snippet bleiben unverändert in der Route. Proof: pnpm --filter @hivegrid/web typecheck grün. Noch nicht als vollständig erledigt gezählt: kompletter bespoke Builder-Canvas (S02/Advanced), Public-Form-States und Submission-Detail-Feinschnitt.

2026-07-10 UI-Bugfix: Rekursive Subframe-App-Shell entfernt. FormsAdminPage rendert jetzt nur noch app-chrome-freien Content und importiert nicht mehr ~/ui/layouts/DefaultPageLayout, damit die echte HiveGrid-Sidebar nicht doppelt erscheint. Proof: Regressionstest apps/web/app/components/screens/subframe-layout-boundary.test.ts.

2026-07-10 Subframe-UI-Nachzug (vollständiger D-FORM-Swap): Alle Screens des Subframe-Flows „(MCP) WF-P16 Form Builder" integriert, Loader/Action/Permissions/Owner-Filter unverändert:

  • /forms (S00): FormsAdminPage auf Soll gehoben — Status-/Art-Filterzeilen, Such-/Sortier-Selects, Zeilen-Dropdown (Veröffentlichen/Duplizieren/Link kopieren/Antworten ansehen/Löschen), E01-/E02-Leerzustände; neue List-Ops duplicate (kopiert Definition+Fields+Actions als Draft) und publish.
  • /forms/new (S01): neue Route + FormNewPage (Typ-Karten Website/Lead/Umfrage/Intern → Draft + Redirect in den Editor). FormSubtype-Enum additiv um lead/internal erweitert (Merge-Migration 20260710200000_ak_p16c_form_subtype_lead_internal); Lead-Formulare seeden eine aktive create_lead-Action.
  • /forms/:id (S02/S02L/S03/S05): FormEditorPage + editor/-Screens ersetzen das alte handgeschriebene UI — Tabs Fragen/Design/Antworten (?tab=), debounced Autosave über den unveränderten op=save-Contract, Fragen-Karten mit dnd-kit, Conditional-Logic-Editor, Lead-Banner + S02L-Mapping (vorname/nachname/email/telefon/message, E05-Warnbanner), Design-Tab (primaryColor/fontFamily/backgroundColor/borderRadius + Inhalte + Live-Vorschau), Antworten-Tab (Feld-Spalten, Filter, CSV/PDF-Export mit E04-Fehlerbanner, Detail-Drawer mit ActionLog/Re-Run, E03-Leerzustand); neue Ops duplicate/delete. Altes FormBuilder-Modul bleibt vorerst (PreviewTab/Typen wiederverwendet, Tests grün) — Cleanup als Folgeaufgabe.
  • Public (S04/V01–V03): PublicFormRenderer self-contained restylt (Akzentbalken, Card, Erfolgs-/Fehler-Zustände), neue PublicFormUnavailable-Ansicht statt nacktem 404 auf /f/:tenant/:slug und im Embed (Status 404 bleibt; Embed-ErrorBoundary bekommt x-frame-options: ALLOWALL).
  • Querschnitt: alle Texte via i18n (de+en, settings.forms.{subtype,public,editor,admin.list,admin.new}), subframe-layout-boundary.test.ts um alle neuen Screens erweitert (keine doppelte App-Shell).

Proof: pnpm --filter @hivegrid/web typecheck grün; pnpm exec vitest run über forms.$id.action/defaults/i18n, FormEditorPage, subframe-layout-boundary, formWidget/builder, api.embed.forms.submit(+i18n) = 9 Dateien/30 Tests grün; scripts/i18n-check.ts + verify-hardcoded-strings.mjs exit 0; prisma validate grün.

2026-07-10 Sichtbarkeits-Fix nach staging-Abnahme (Branch akeshan/subframe-forms-sichtbarkeit): Auf staging waren S00-Tabelle und alle Editor-Tab-Inhalte unsichtbar (im DOM vorhanden, 0px hoch). Root-Cause: das Subframe-Export-Muster „Screen-Root h-full min-h-[0px] overflow-hidden + Inhalt in grow shrink-0 basis-0 overflow-y-auto" kollabiert innerhalb der SubframeAppShell, weil deren <main> ein block-level Scroll-Container ohne definite Höhe ist. Fix: beide Container in FormsAdminPage/FormEditorPage (und AutomationPages, gleicher Fehler aus PR #68) auf normalen Dokumentfluss umgestellt; Guard-Regel in subframe-layout-boundary.test.ts verbietet das Muster ab jetzt statisch. Dazu: title im Loader-Payload + meta-Export für /forms, /forms/new, /forms/:id (Breadcrumb zeigte „Dashboard", Tab-Titel nur „HiveGrid"); Demo-Seed um WF-P16-Showcase erweitert (Lead-Formular mit S02L-konformem Mapping + processed/failed/spam-Submissions inkl. ActionLogs, Umfrage mit 3 Antworten, internes Formular als Entwurf für E03; ungültiges Mapping-Target full_name→name der Bestandsformulare auf nachname normalisiert).

2026-07-11 Soll/Ist-Verifikation Subframe-MCP: Abgleich des integrierten Stands gegen den Live-Flow „(MCP) WF-P16 Form Builder" (16 Pages) via Subframe-MCP: kein neues oder geändertes Page-Delta seit dem vollständigen Swap vom 2026-07-10 — einzige Änderung ist S01B Gefuehrter Fragen Editor _backlog_ (explizit Backlog, out of scope). Die Integrations-Branches akeshan/subframe-forms-sichtbarkeit und akeshan/subframe-forms-vervollstaendigung sind vollständig in main gemerged (je 0 Commits ahead). Kein UI-Handlungsbedarf; offene Punkte unverändert nur die Doku-Nachzüge unten.

2026-07-17 Stand-Audit + Restarbeiten (Branch fix/ak-p16-audit-restwork): Das Audit fand eine unbemerkte Regression aus dem Subframe-Swap (PR #71): die FormAction-Konfigurationsoberfläche (Notiz vom 01.07.: „Admin-Konfiguration für FormAction im Builder ergänzt") war nach dem Swap bis auf create_lead (S02L-Mapping) nicht mehr erreichbar — die übrigen Action-Typen (Kontakt/Projekt/Task, Team-/Submitter-Mail, Webhook, Automation-Trigger, Auto-Match, Double-Opt-in) liefen im Worker, hatten aber keine UI. Fix: der bestehende SettingsTab (alle Action-Typen + Field-Mapping + Delivery-Settings) ist als vierter Editor-Tab ?tab=aktionen wieder eingebunden; Persistenz über den unveränderten op=save-Contract (trug settings.actions bereits). i18n-Tab-Titel de+en ergänzt, FormEditorPage.test.tsx um den Tab erweitert. Dazu der nachgetragene e2e-Smoke (DoD-Punkt oben) mit neuem ui.forms.list-Marker. Kleinbefund notiert (kein DoD-Bruch): Re-Run arbeitet auf Submission-Ebene (Re-Queue der gesamten Verarbeitung), FormActionLog.rerunOfLogId ist ungenutzt — Per-Action-Re-Run nur als Vorschlag außerhalb Scope.

Noch offen

Selbst machbar im Ticket-Scope:

  • Aktuell keine offenen selbst machbaren Dev-Punkte identifiziert. Der funktionale AK-P16c-Umfang aus der DoD ist umgesetzt und lokal verifiziert.

Design-Nachzug-Rest (Soll-Elemente ohne Backend — bei Bedarf als CR/Folge-Ticket):

  • Versionsverlauf (Header-Dropdown S02/S03/S05) — kein Versions-Backend.
  • Theme-Logo-Upload + Formularbreite (S03) — FormTheme kennt nur primaryColor/backgroundColor/textColor/fontFamily/borderRadius.
  • Lead-Mapping-Zeilen „Bereich"/„Datei/Bild"/„Pipeline" (S02L) — create_lead unterstützt nur vorname/nachname/email/telefon/message, InboxLead hat keine Pipeline/Tags.
  • „Optionen mischen" (S02) — kein Schema-Feld.
  • Visual-Regression-Baseline (M016) für die neuen Screens + Hot-Swap-Drill laufen CI-seitig (lokal Windows nicht möglich, siehe Memory) — Re-Baseline beim nächsten CI-Lauf prüfen.

Extern/blockiert:

  • Doku-Nachzüge: Spec/ENTITY-MODEL, REQUIREMENTS/ROADMAP und Plane-Ticket final abgleichen.

Bewusst v2 laut Ticket-Text:

  • Personalisierte Links/FormLink bleiben v2.
  • JS-Snippet ist laut Ticket-Text v2; v1 deckt Public URL, QR und iFrame ab.

Technische Bausteine

  • Entities (eigene prisma/schema/forms.prisma): Form (slug, subtype standard/acceptance_form/onboarding/survey, status, is_public), FormField (field_key, field_type 12 Typen, required, validation_rules), FormSubmission (submission_data JSON, linked_entity_type/id polymorph), FormFile (→ File), FormAction (action_type send_email/create_lead/create_projekt/webhook/trigger_automation, action_config). crm.prisma/tasks.prisma/automation.prisma nur über Actions berührt (AD-21).
  • Conditional-Logic-Engine (Wenn-Dann auf field_key) client- und serverseitig validiert.
  • Post-Submit-Pipeline: Field-Mapping → typsichere Actions → FormActionLog (idempotent, Re-Run); Auto-Match auf Kontakt/Lead.
  • Public-Hardening: mCaptcha + Rate-Limit (AK-INFRA2), DSGVO-Pflichtfelder.
  • RLS überall (außer öffentlicher Render-Pfad ist read-only auf publizierte Forms); is_demo_data auf SHK-Template-Seeds.

Quellen (granular)

  • ENTITY-MODEL.md → Domäne 9 (Form, FormField, FormSubmission, FormFile, FormAction; FormLink = v2)
  • REQUIREMENTS.md → REQ-form-datenmodell (FormLink/JS-Snippet → v2), REQ-form-editor, REQ-form-actions
  • ROADMAP.md → Phase 16 · Milestones: (M121-editor, M122-veroeffentlichung gedünnt, M123-submission-eingang, M124-conditional-display, M125-rate-limit-captcha-dsgvo)
  • designer-briefs/P16-kalender-booking-forms-signatur.md (Gruppe 3 Form-Builder; URL+QR+iFrame v1)

Dev-Nachzug (nach Davids D-FORM/D-P16-Delta)

  • Subframe-UI-Nachzug für Forms-Verwaltung (S00, /forms) integriert
  • App-Shell-Grenze nachgezogen: keine generierte Subframe-Sidebar innerhalb der HiveGrid-App-Shell
  • Vollständiger D-FORM-Swap für Builder/Public/Submissions geprüft und nachgezogen (2026-07-10; Rest-Delta ohne Backend siehe „Noch offen")
  • Spec/ENTITY-MODEL an Davids UI-Entscheidungen angepasst
  • REQUIREMENTS/ROADMAP nachgezogen
  • Plane-Ticket AK-P16c mit Subframe-UI-Nachzug aktualisiert