feat: person identity matching with detection, confirmation and audit trail

Implements enterprise-grade identity resolution (detect → suggest → confirm)
for Person ↔ User linking. Matches are detected automatically on person
creation and user account creation, then surfaced to organisers for explicit
confirmation or dismissal. No silent auto-linking.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

api/app/Http/Controllers/Api/V1/PersonController.php

@@ -11,17 +11,22 @@ use App\Http\Resources\Api\V1\PersonCollection;
 use App\Http\Resources\Api\V1\PersonResource;
 use App\Models\Event;
 use App\Models\Person;
+use App\Services\PersonIdentityService;
 use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Gate;
 
 final class PersonController extends Controller
 {
+    public function __construct(
+        private readonly PersonIdentityService $identityService,
+    ) {}
+
     public function index(Request $request, Event $event): PersonCollection
     {
         Gate::authorize('viewAny', [Person::class, $event]);
 
-        $query = $event->persons()->with('crowdType');
+        $query = $event->persons()->with(['crowdType', 'pendingIdentityMatch.matchedUser']);
 
         if ($request->filled('crowd_type_id')) {
             $query->where('crowd_type_id', $request->input('crowd_type_id'));
@@ -72,6 +77,8 @@ final class PersonController extends Controller
 
         $person = $event->persons()->create($request->validated());
 
+        $this->identityService->detectMatchForPerson($person);
+
         return $this->created(new PersonResource($person->fresh()->load('crowdType')));
     }
 

api/app/Http/Controllers/Api/V1/PersonIdentityMatchController.php

@@ -0,0 +1,120 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\V1\BulkConfirmIdentityMatchesRequest;
+use App\Http\Resources\Api\V1\PersonIdentityMatchResource;
+use App\Models\Organisation;
+use App\Models\Person;
+use App\Models\PersonIdentityMatch;
+use App\Services\PersonIdentityService;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+use Illuminate\Support\Facades\Gate;
+
+final class PersonIdentityMatchController extends Controller
+{
+    public function __construct(
+        private readonly PersonIdentityService $identityService,
+    ) {}
+
+    public function index(Request $request, Organisation $organisation): AnonymousResourceCollection
+    {
+        Gate::authorize('viewAny', [PersonIdentityMatch::class, $organisation]);
+
+        $eventIds = $organisation->events()->pluck('id');
+
+        $matches = PersonIdentityMatch::pending()
+            ->whereHas('person', fn ($q) => $q->whereIn('event_id', $eventIds))
+            ->with(['person.crowdType', 'person.event', 'matchedUser'])
+            ->orderBy('created_at', 'desc')
+            ->paginate(25);
+
+        return PersonIdentityMatchResource::collection($matches);
+    }
+
+    public function showForPerson(Organisation $organisation, Person $person): PersonIdentityMatchResource
+    {
+        Gate::authorize('view', [$person, $person->event]);
+
+        $match = $person->pendingIdentityMatch()
+            ->with('matchedUser')
+            ->firstOrFail();
+
+        return new PersonIdentityMatchResource($match);
+    }
+
+    public function confirm(Request $request, Organisation $organisation, PersonIdentityMatch $personIdentityMatch): JsonResponse
+    {
+        Gate::authorize('confirm', $personIdentityMatch);
+
+        try {
+            $this->identityService->confirmMatch($personIdentityMatch, $request->user());
+        } catch (\DomainException $e) {
+            return $this->error($e->getMessage(), 422);
+        }
+
+        $personIdentityMatch->refresh()->load(['person.crowdType', 'person.event', 'matchedUser', 'resolvedBy']);
+
+        return $this->success(new PersonIdentityMatchResource($personIdentityMatch));
+    }
+
+    public function dismiss(Request $request, Organisation $organisation, PersonIdentityMatch $personIdentityMatch): JsonResponse
+    {
+        Gate::authorize('dismiss', $personIdentityMatch);
+
+        try {
+            $this->identityService->dismissMatch($personIdentityMatch, $request->user());
+        } catch (\DomainException $e) {
+            return $this->error($e->getMessage(), 422);
+        }
+
+        $personIdentityMatch->refresh()->load(['person.crowdType', 'person.event', 'matchedUser', 'resolvedBy']);
+
+        return $this->success(new PersonIdentityMatchResource($personIdentityMatch));
+    }
+
+    public function bulkConfirm(BulkConfirmIdentityMatchesRequest $request, Organisation $organisation): JsonResponse
+    {
+        Gate::authorize('bulkConfirm', [PersonIdentityMatch::class, $organisation]);
+
+        $matches = PersonIdentityMatch::whereIn('id', $request->validated('match_ids'))
+            ->with('person')
+            ->get()
+            ->keyBy('id');
+
+        $confirmed = 0;
+        $errors = [];
+
+        foreach ($request->validated('match_ids') as $matchId) {
+            $match = $matches->get($matchId);
+
+            if ($match === null) {
+                $errors[] = ['match_id' => $matchId, 'error' => 'Match not found.'];
+                continue;
+            }
+
+            $response = Gate::inspect('update', [$match->person, $match->person->event]);
+            if ($response->denied()) {
+                $errors[] = ['match_id' => $matchId, 'error' => 'Unauthorized.'];
+                continue;
+            }
+
+            try {
+                $this->identityService->confirmMatch($match, $request->user());
+                $confirmed++;
+            } catch (\DomainException $e) {
+                $errors[] = ['match_id' => $matchId, 'error' => $e->getMessage()];
+            }
+        }
+
+        return response()->json([
+            'confirmed' => $confirmed,
+            'errors' => $errors,
+        ]);
+    }
+}

api/app/Http/Requests/Api/V1/BulkConfirmIdentityMatchesRequest.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Requests\Api\V1;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+final class BulkConfirmIdentityMatchesRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /** @return array<string, mixed> */
+    public function rules(): array
+    {
+        return [
+            'match_ids' => ['required', 'array', 'min:1', 'max:100'],
+            'match_ids.*' => ['required', 'string', 'exists:person_identity_matches,id'],
+        ];
+    }
+}

api/app/Http/Resources/Api/V1/PersonIdentityMatchResource.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Http\Resources\Api\V1;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+final class PersonIdentityMatchResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'person' => [
+                'id' => $this->person->id,
+                'name' => $this->person->name,
+                'email' => $this->person->email,
+                'crowd_type' => $this->whenLoaded('person', fn () =>
+                    $this->person->crowdType?->name
+                ),
+                'event' => $this->whenLoaded('person', fn () => [
+                    'id' => $this->person->event_id,
+                    'name' => $this->person->event?->name,
+                ]),
+            ],
+            'matched_user' => [
+                'id' => $this->matchedUser->id,
+                'name' => $this->matchedUser->name,
+                'email' => $this->matchedUser->email,
+            ],
+            'matched_on' => $this->matched_on->value,
+            'confidence' => $this->confidence->value,
+            'status' => $this->status->value,
+            'resolved_by' => $this->when($this->resolvedBy, fn () => [
+                'id' => $this->resolvedBy->id,
+                'name' => $this->resolvedBy->name,
+            ]),
+            'resolved_at' => $this->resolved_at?->toISOString(),
+            'created_at' => $this->created_at->toISOString(),
+        ];
+    }
+}

api/app/Http/Resources/Api/V1/PersonResource.php

@@ -24,6 +24,23 @@ final class PersonResource extends JsonResource
             'created_at' => $this->created_at->toIso8601String(),
             'crowd_type' => new CrowdTypeResource($this->whenLoaded('crowdType')),
             'company' => new CompanyResource($this->whenLoaded('company')),
+            'pending_identity_match' => $this->when(
+                $this->relationLoaded('pendingIdentityMatch') && $this->pendingIdentityMatch,
+                function () {
+                    $match = $this->pendingIdentityMatch;
+
+                    return [
+                        'match_id' => $match->id,
+                        'matched_user' => [
+                            'id' => $match->matchedUser->id,
+                            'name' => $match->matchedUser->name,
+                            'email' => $match->matchedUser->email,
+                        ],
+                        'matched_on' => $match->matched_on->value,
+                        'confidence' => $match->confidence->value,
+                    ];
+                }
+            ),
             'tags' => $this->when(
                 $this->user_id && $this->relationLoaded('user'),
                 function () {