Memory Wiki

Write 3 detailed TA build briefs for Module 8 (Forms) at /root/.hermes/plans/task-t43/t44/t45-build-plan.md. Read the PB at /root/.hermes/plans/pb-m8-forms.md for full specs. Each brief must be implementation-ready — TB should be able to code directly from it. ## T43 — Form Engine (the core) Write to /root/.hermes/plans/task-t43-build-plan.md Form schema CRUD. 11 field types. Conditional logic engine. Multi-step wizard. Form templates. Versioning. API endpoints. **Interface**: FormEngineInterface with methods for CRUD forms, fields, conditional rules, templates, versions. **Key specs from PB:** - 11 field types: text, email, select, checkbox, radio, textarea, file_upload, stripe_payment, membership_tier, billing_interval, hidden - Conditional logic as JSON rules: `{field_id, operator, value, action: show/hide/require, target_field_id}` - Multi-step pages: forms have ordered page groups, each page can have conditional visibility - Versioning: snapshot schema on each save, stored in profe_form_versions - Templates: pre-built registration, payment, contact, survey **Routes:** - POST/GET forms - PUT/DELETE forms/{id} - GET forms/{id}/schema (returns compiled schema for frontend renderer) - POST forms/{id}/fields - PUT/DELETE forms/{id}/fields/{fieldId} - POST forms/{id}/conditional-rules - POST forms/templates (load from template) - GET forms/templates **Migration SQL**: 045_create_profe_form_schemas.sql, 046_create_profe_form_versions.sql. Must have -- UP / -- DOWN markers. Table naming: profe_form_schemas, profe_form_versions. Proper indexes. ## T44 — Form Submissions (the runtime) Write to /root/.hermes/plans/task-t44-build-plan.md Entry storage. Post-submit pipeline (8 configurable steps). Stripe Elements integration. WP user creation. Abandoned cart cron. Free vs paid fork. **Interface**: FormSubmissionsInterface with methods for submit, getSubmission, getSubmissions, exportSubmissions, deleteSubmission, processPipeline, detectAbandoned. **Pipeline steps (configurable per form):** 1. validate — validate fields + conditional rules + spam check 2. process_payment — create Stripe PaymentIntent, handle result 3. create_wp_user — wp_insert_user, password generated or user-provided 4. assign_membership — set profe_users.membership_level 5. sync_crm — crm_sync->enqueueContactCreate(userId) 6. send_notifications — mail_queue for confirmation + admin alert 7. track_conversion — Google Ads via google_ads_conversion 8. notify_admin — email to admin with submission details **Abandoned cart:** - Save submission at each step (status: started / completed / failed / pending_payment / abandoned) - Cron job: scan for status=started or payment_pending older than 1hr, mark abandoned, fire profe/form/abandoned event - Stripe webhooks handle payment-stage abandonment (checkout.session.expired) **Free vs Paid fork:** - submission.payment_status = null (free, create immediately) / pending (waiting for Stripe webhook) / completed / failed - For paid: save submission with payment_pending status, return after Stripe webhook to create user **Routes:** - POST forms/{formId}/submit (public, CSRF-exempt via nonce in form) - GET forms/{formId}/submissions (admin) - GET forms/{formId}/submissions/{id} (admin) - GET forms/{formId}/export (admin, CSV) - DELETE forms/{formId}/submissions/{id} (admin, CSRF) - POST admin/forms/abandoned/scan (admin, trigger cron manually) **Migration SQL**: 047_create_profe_form_submissions.sql. Must have -- UP / -- DOWN markers. Table: profe_form_submissions with proper indexes for abandoned detection (status + started_at). ## T45 — Form Admin (the UI) Write to /root/.hermes/plans/task-t45-build-plan.md React SPA drag-and-drop form builder. Conditional logic visual editor. Analytics dashboard. Entry management. **Interface**: FormAdminInterface with methods for dashboard stats, builder config, analytics data. **Key features (these describe what the React SPA needs, not PHP interfaces):** - Drag-and-drop field palette to canvas - Each field has settings panel (label, placeholder, required, options for select/radio, conditional logic) - Conditional logic visual editor: "If [field] [operator] [value] then [action] [target field]" - Multi-step page management: add/remove/reorder pages - Preview mode: render the form as user would see it - Template browser: load/create from templates - Submission viewer: table with search, filter by status, click to view - Export button (CSV) - Analytics dashboard: total submissions, completion rate, abandonment rate, funnel visualization (step-by-step drop-off) - Form settings: email recipients, success URL, pipeline step toggles, spam settings **This task's PHP backend provides:** - GET admin/forms/dashboard — submission stats, funnel data - GET admin/forms/{id}/analytics — per-form analytics - GET admin/forms/{id}/submissions — paginated submission list - GET admin/forms/{id}/export — CSV download - PUT admin/forms/{id}/settings — update form settings **Analytics tracking:** - profe_form_analytics table: form_id, event_type (view/start/step/complete/abandon/payment_start/success/fail), step_number, user_id, created_at - Frontend fires analytics events via REST API - Indexes on form_id + event_type + created_at **Migration SQL**: 048_create_profe_form_analytics.sql. -- UP / -- DOWN markers. ## For ALL briefs - Each brief: overview, interface contract (exact PHP), DDL, REST routes, dependencies, events, implementation plan, test plan (≥12 tests) - Migration version numbers: 045-048 for Module 8 (current highest is 052 from Module 7, so use 053-056) - Table naming: profe_form_ prefix - Use 2 backslashes in PHP strings: `'Profe\\\\CoreUsers\\\\CoreUsersInterface'` - No FAULT-011 violations - All SQL files need -- UP / -- DOWN markers