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

129 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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