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,
+        ]);
+    }
+}