From b7bd7904c2da7ed2ad92f50c04c4a3afc4c31d01 Mon Sep 17 00:00:00 2001
From: "bert.hausmans" <bert@hausmans.nl>
Date: Fri, 8 May 2026 01:59:10 +0200
Subject: [PATCH] feat(form-builder): FormSubmissionIdentityMatchResolved
 broadcast event
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per RFC-WS-6 §Q1 v1.3 addition 2.

Broadcast event class only — not yet dispatched. D2 wires the dispatch
call into TriggerPersonIdentityMatchOnFormSubmit::handle (after the
final identity_match_status write), and the channel-authorization
callback into routes/channels.php.

Frontend Echo subscription is a separate frontend follow-up (out of
WS-6 v1.3-delta scope).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 .../FormSubmissionIdentityMatchResolved.php   | 58 +++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 api/app/Events/FormBuilder/FormSubmissionIdentityMatchResolved.php

diff --git a/api/app/Events/FormBuilder/FormSubmissionIdentityMatchResolved.php b/api/app/Events/FormBuilder/FormSubmissionIdentityMatchResolved.php
new file mode 100644
index 00000000..a3da5719
--- /dev/null
+++ b/api/app/Events/FormBuilder/FormSubmissionIdentityMatchResolved.php
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Events\FormBuilder;
+
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Broadcasting\PrivateChannel;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcast;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+
+/**
+ * Broadcast when TriggerPersonIdentityMatchOnFormSubmit (D2) writes the
+ * final identity_match_status. Frontend portal IdentityMatchBanner
+ * subscribes to this channel and refetches the submission resource on
+ * receipt, so the banner copy transitions from "we're checking matches…"
+ * to the final state without a manual reload.
+ *
+ * Per RFC-WS-6 §Q1 v1.3 addition 2.
+ *
+ * Wiring (the dispatch call from TriggerPersonIdentityMatchOnFormSubmit::handle)
+ * lands in D2. This class exists in D1 so D2's wiring is a one-liner.
+ */
+final class FormSubmissionIdentityMatchResolved implements ShouldBroadcast
+{
+    use Dispatchable;
+    use InteractsWithSockets;
+    use SerializesModels;
+
+    public function __construct(
+        public readonly string $submissionId,
+        public readonly string $status,        // 'matched' | 'no_match' | 'multiple_candidates'
+        public readonly int $matchCount,
+    ) {}
+
+    /**
+     * Private channel keyed on submission ULID.
+     *
+     * Frontend subscribes via `Echo.private('submission.${submissionId}')`.
+     * Authorization (only the submitter / organisation admins can subscribe)
+     * is the responsibility of the channel-authorization callback in
+     * routes/channels.php — that wiring lands in D2 alongside the dispatch.
+     *
+     * @return array<int, PrivateChannel>
+     */
+    public function broadcastOn(): array
+    {
+        return [
+            new PrivateChannel("submission.{$this->submissionId}"),
+        ];
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'identity-match.resolved';
+    }
+}