129 lines
16 KiB
Markdown
129 lines
16 KiB
Markdown
# 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
|
||
- [x] **12 Feld-Typen** + **Conditional Logic** + Validierung pro Feld + geseedete **SHK-Templates** + Live-Vorschau
|
||
- [x] **Embed**: öffentliche URL + QR + iFrame (personalisierte Links / JS-Snippet → v2)
|
||
- [x] **Post-Submit-Actions** (Lead/Kontakt/Projekt/Task, Email, Webhook, Automation-Trigger, Auto-Match) mit **Field-Mapping** + **ActionLog** (Re-Run)
|
||
- [x] **Rate-Limit + mCaptcha + DSGVO-Pflicht** auf öffentlichen Endpunkten; Race-Schutz beim Submit
|
||
- [x] **Form-Renderer als wiederverwendbare Komponente** (Booking-Intake, HR-Anträge)
|
||
- [x] Permission-Bundle `forms.*` (basic/builder/publisher/admin) serverseitig Owner-gefiltert
|
||
- [x] Konnektor `tenantHasModule('forms')`; RLS auf allen Tenant-Tabellen
|
||
- [x] **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)
|
||
- [x] Subframe-UI-Nachzug für Forms-Verwaltung (`S00`, `/forms`) integriert
|
||
- [x] App-Shell-Grenze nachgezogen: keine generierte Subframe-Sidebar innerhalb der HiveGrid-App-Shell
|
||
- [x] 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
|
||
- [x] Plane-Ticket `AK-P16c` mit Subframe-UI-Nachzug aktualisiert
|