From 71d2b4294d9b30a61c8de306c32e8f618885c2e7 Mon Sep 17 00:00:00 2001 From: "bert.hausmans" Date: Fri, 17 Apr 2026 23:03:12 +0200 Subject: [PATCH] feat(form-builder): schema drift detection + PUT auto_save_count S2c D5 completion: schema_version_at_open column + drift semantics. - Migration 2026_04_22_100002 adds unsignedInteger schema_version_at_open. Recorded by FormSubmissionService::createDraft at the moment the portal first renders the form. - PublicFormSubmissionResource.schema_drift now compares schema_version_at_open vs schema_version_at_submit (or schema.version for active drafts) so organiser edits during an open draft surface as drift on subsequent PUT/submit responses. - PublicFormSubmissionController::update routes through FormSubmissionService::saveDraft so auto_save_count increments and the FormSubmissionDraftUpdated event fires per PUT. - bootstrap/app.php: FormRequest ValidationException on /api/v1/public/forms/* is now re-wrapped into the D6 envelope with code=VALIDATION_FAILED, so public endpoints emit one consistent error shape regardless of layer. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../PublicFormSubmissionController.php | 7 +++-- .../PublicFormSubmissionResource.php | 29 ++++++++++++------- api/app/Models/FormBuilder/FormSubmission.php | 2 ++ .../FormBuilder/FormSubmissionService.php | 1 + api/bootstrap/app.php | 15 ++++++++++ ...ma_version_at_open_to_form_submissions.php | 28 ++++++++++++++++++ 6 files changed, 69 insertions(+), 13 deletions(-) create mode 100644 api/database/migrations/2026_04_22_100002_add_schema_version_at_open_to_form_submissions.php diff --git a/api/app/Http/Controllers/Api/V1/FormBuilder/PublicFormSubmissionController.php b/api/app/Http/Controllers/Api/V1/FormBuilder/PublicFormSubmissionController.php index e78807e3..07145024 100644 --- a/api/app/Http/Controllers/Api/V1/FormBuilder/PublicFormSubmissionController.php +++ b/api/app/Http/Controllers/Api/V1/FormBuilder/PublicFormSubmissionController.php @@ -86,12 +86,13 @@ final class PublicFormSubmissionController extends Controller $values = (array) ($request->validated('values') ?? []); if ($values !== []) { - // Service throws FieldValidationException (422) on validation - // failure; the handler renders the standardised envelope. - $this->valueService->upsertMany($submission, $values, null); + // saveDraft → upsertMany + auto_save_count++ + FormSubmissionDraftUpdated + // event. FieldValidationException bubbles to the D6 envelope. + $this->submissionService->saveDraft($submission, $values, null); } if ($request->filled('first_interacted_at')) { + $submission->refresh(); $submission->first_interacted_at ??= $request->validated('first_interacted_at'); $submission->save(); } diff --git a/api/app/Http/Resources/FormBuilder/PublicFormSubmissionResource.php b/api/app/Http/Resources/FormBuilder/PublicFormSubmissionResource.php index f086bb48..b9ab699e 100644 --- a/api/app/Http/Resources/FormBuilder/PublicFormSubmissionResource.php +++ b/api/app/Http/Resources/FormBuilder/PublicFormSubmissionResource.php @@ -69,21 +69,30 @@ final class PublicFormSubmissionResource extends JsonResource private function computeSchemaDrift(): bool { - if ($this->schema_version_at_submit === null) { - // Draft phase: drift is "version advanced since the submission - // was opened". We use schema.version vs the version the portal - // saw via PublicFormSchemaResource at open time — which is - // only derivable after submit. For drafts, schema_drift stays - // false; the submit response is the authoritative check. + // The draft was opened against version_at_open; at submit time the + // schema's current version is frozen into version_at_submit. Drift + // means the organiser edited the schema between the portal loading + // the form and the user hitting submit. + // + // Drafts without a submit stamp keep the comparison live against + // the current schema.version so an organiser edit during an open + // draft also surfaces drift on subsequent PUT/GET calls. + + $atOpen = $this->schema_version_at_open; + if ($atOpen === null) { return false; } - $schema = $this->schema; - if ($schema === null) { - return false; + $other = $this->schema_version_at_submit; + if ($other === null) { + $schema = $this->schema; + if ($schema === null) { + return false; + } + $other = (int) $schema->version; } - return (int) $schema->version !== (int) $this->schema_version_at_submit; + return (int) $atOpen !== (int) $other; } /** diff --git a/api/app/Models/FormBuilder/FormSubmission.php b/api/app/Models/FormBuilder/FormSubmission.php index 12a88dca..c2641ab5 100644 --- a/api/app/Models/FormBuilder/FormSubmission.php +++ b/api/app/Models/FormBuilder/FormSubmission.php @@ -40,6 +40,7 @@ final class FormSubmission extends Model 'reviewed_at', 'review_notes', 'submitted_at', + 'schema_version_at_open', 'schema_version_at_submit', 'schema_snapshot', 'submission_duration_seconds', @@ -65,6 +66,7 @@ final class FormSubmission extends Model 'opened_at' => 'datetime', 'first_interacted_at' => 'datetime', 'public_submitter_ip_anonymised_at' => 'datetime', + 'schema_version_at_open' => 'int', 'schema_version_at_submit' => 'int', 'submission_duration_seconds' => 'int', 'auto_save_count' => 'int', diff --git a/api/app/Services/FormBuilder/FormSubmissionService.php b/api/app/Services/FormBuilder/FormSubmissionService.php index f0198b50..6eba14f2 100644 --- a/api/app/Services/FormBuilder/FormSubmissionService.php +++ b/api/app/Services/FormBuilder/FormSubmissionService.php @@ -61,6 +61,7 @@ final class FormSubmissionService $submission->status = FormSubmissionStatus::DRAFT->value; $submission->is_test = (bool) ($context['is_test'] ?? false); $submission->opened_at = $context['opened_at'] ?? now(); + $submission->schema_version_at_open = (int) $schema->version; $submission->idempotency_key = $context['idempotency_key'] ?? null; $submission->public_submitter_name = $context['public_submitter_name'] ?? null; $submission->public_submitter_email = $context['public_submitter_email'] ?? null; diff --git a/api/bootstrap/app.php b/api/bootstrap/app.php index b1e3ceb4..3194ba61 100644 --- a/api/bootstrap/app.php +++ b/api/bootstrap/app.php @@ -52,6 +52,21 @@ return Application::configure(basePath: dirname(__DIR__)) return response()->json($body, $e->status, $e->headers); }); + // FormRequest validation on /api/v1/public/forms/* → rewrap into + // the D6 envelope so every public endpoint error looks identical + // regardless of which layer surfaced it. + $exceptions->render(function (ValidationException $e, Request $request) { + if (! $request->is('api/v1/public/forms/*')) { + return null; + } + + return response()->json([ + 'message' => $e->getMessage(), + 'code' => 'VALIDATION_FAILED', + 'errors' => $e->errors(), + ], $e->status); + }); + // Database connection / query errors → 503 $exceptions->render(function (QueryException|PDOException $e, Request $request) { if ($request->expectsJson() || $request->is('api/*')) { diff --git a/api/database/migrations/2026_04_22_100002_add_schema_version_at_open_to_form_submissions.php b/api/database/migrations/2026_04_22_100002_add_schema_version_at_open_to_form_submissions.php new file mode 100644 index 00000000..f7ac8f93 --- /dev/null +++ b/api/database/migrations/2026_04_22_100002_add_schema_version_at_open_to_form_submissions.php @@ -0,0 +1,28 @@ +unsignedInteger('schema_version_at_open')->nullable()->after('opened_at'); + }); + } + + public function down(): void + { + Schema::table('form_submissions', function (Blueprint $table): void { + $table->dropColumn('schema_version_at_open'); + }); + } +};