bert.hausmans/crewli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: complete person identity matching system with fuzzy detection, revert, and manual link

Browse Source 
Implements the full identity matching engine: email matching (HIGH confidence),
fuzzy name matching with Levenshtein distance (MEDIUM confidence, upgradable to
HIGH with DOB tiebreaker), manual link/unlink, revert confirmed matches, and
automatic detection via PersonObserver. Includes 33 comprehensive tests, frontend
integration with confirm/dismiss/unlink UI, and match indicators in the persons list.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
bert.hausmans
2026-04-14 08:44:24 +02:00
parent 7932e53daf
commit eb1a0ac666
30 changed files with 1941 additions and 399 deletions
Download Patch File Download Diff File Expand all files Collapse all files

425
api/app/Services/PersonIdentityService.php
View File

@@ -7,78 +7,219 @@ namespace App\Services;
use App\Enums\IdentityMatchConfidence;
use App\Enums\IdentityMatchMethod;
use App\Enums\IdentityMatchStatus;
use App\Models\Event;
use App\Models\Person;
use App\Models\PersonIdentityMatch;
use App\Models\User;
use Illuminate\Support\Collection;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use Illuminate\Validation\ValidationException;
final class PersonIdentityService
{
/**
* Detect if a person's email matches an existing user account.
* Called after a person is created. Does NOT auto-link.
* Calculate whether two name strings are a fuzzy match using Levenshtein distance
* with a length-adaptive threshold.
*/
private function isFuzzyNameMatch(string $a, string $b): bool
{
$a = mb_strtolower(trim($a));
$b = mb_strtolower(trim($b));
if ($a === $b) {
return true;
}
$maxLen = max(strlen($a), strlen($b));
// For very short names (< 4 chars), require exact match
if ($maxLen < 4) {
return false;
}
// Adaptive threshold: 2 for names ≤ 10 chars, 3 for longer
$threshold = $maxLen <= 10 ? 2 : 3;
return levenshtein($a, $b) <= $threshold;
}
/**
* Detect potential matches for a person.
* Called when a Person is created or email is updated.
*
* Detection strategy (in order of confidence):
* 1. Exact email match within org → HIGH confidence
* 2. Fuzzy name match + optional DOB tiebreaker → MEDIUM (or HIGH if DOB matches)
*/
public function detectMatchForPerson(Person $person): ?PersonIdentityMatch
{
// Guard 1: Person already linked to a user
$matches = $this->detectMatches($person);
return $matches->first();
}
/**
* Detect all potential matches for a person.
*/
public function detectMatches(Person $person): Collection
{
if ($person->user_id !== null) {
return null;
return collect();
}
// Guard 2: Person has no email
if ($person->email === null || trim($person->email) === '') {
return null;
}
// Guard 3: Person is soft-deleted
if ($person->trashed()) {
return null;
return collect();
}
// Guard 4: Find user with matching normalised email.
// StorePersonRequest validates 'email' as required + email format but does not
// enforce lowercase. User emails are also not guaranteed lowercase. We use
// LOWER() on both sides as a safety net for case-insensitive matching.
$normalised = strtolower(trim($person->email));
$user = User::whereRaw('LOWER(email) = ?', [$normalised])->first();
if ($user === null) {
return null;
if (! $person->email && ! $person->first_name) {
return collect();
}
// Guard 5: User already has a person record in the same event
// (would violate UNIQUE(event_id, user_id) WHERE user_id IS NOT NULL)
$alreadyLinkedInEvent = Person::where('event_id', $person->event_id)
$event = $person->event;
if (! $event) {
return collect();
}
$organisationId = $event->organisation_id;
$matches = collect();
// Get all users in this organisation (one query, reuse for all checks)
$orgUsers = User::whereHas('organisations', fn ($q) => $q->where('organisations.id', $organisationId))->get();
// === Strategy 1: Exact email match ===
if ($person->email) {
$normalised = strtolower(trim($person->email));
$emailMatches = $orgUsers->filter(
fn (User $u) => strtolower(trim($u->email)) === $normalised
);
foreach ($emailMatches as $user) {
$match = $this->createMatchIfEligible(
$person, $user, IdentityMatchMethod::EMAIL, IdentityMatchConfidence::HIGH,
['email'], $organisationId
);
if ($match) {
$matches->push($match);
}
}
}
// === Strategy 2: Fuzzy name match (only if no email match found) ===
if ($matches->isEmpty() && $person->first_name && $person->last_name) {
$nameMatches = $orgUsers->filter(function (User $user) use ($person) {
// Skip if same email (already handled above, or would be email match)
if ($person->email && strtolower(trim($user->email)) === strtolower(trim($person->email))) {
return false;
}
if (! $user->first_name || ! $user->last_name) {
return false;
}
return $this->isFuzzyNameMatch($person->first_name, $user->first_name)
&& $this->isFuzzyNameMatch($person->last_name, $user->last_name);
});
foreach ($nameMatches as $user) {
$confidence = IdentityMatchConfidence::MEDIUM;
$matchedFields = [];
// Check exact name match vs fuzzy
if (mb_strtolower(trim($person->first_name)) === mb_strtolower(trim($user->first_name))
&& mb_strtolower(trim($person->last_name)) === mb_strtolower(trim($user->last_name))) {
$matchedFields[] = 'first_name';
$matchedFields[] = 'last_name';
} else {
$matchedFields[] = 'first_name_fuzzy';
$matchedFields[] = 'last_name_fuzzy';
}
// DOB tiebreaker: upgrades medium → high
if ($person->date_of_birth && $user->date_of_birth
&& $person->date_of_birth->equalTo($user->date_of_birth)) {
$confidence = IdentityMatchConfidence::HIGH;
$matchedFields[] = 'date_of_birth';
}
$match = $this->createMatchIfEligible(
$person, $user, IdentityMatchMethod::NAME_FUZZY, $confidence,
$matchedFields, $organisationId
);
if ($match) {
$matches->push($match);
}
}
}
return $matches;
}
/**
* Create a match record if eligible (no existing match, no conflict).
*/
private function createMatchIfEligible(
Person $person,
User $user,
IdentityMatchMethod $method,
IdentityMatchConfidence $confidence,
array $matchedFields,
string $organisationId,
): ?PersonIdentityMatch {
// Skip if user already linked to a person at this event with same crowd type
$alreadyLinked = Person::withoutGlobalScopes()
->where('event_id', $person->event_id)
->where('user_id', $user->id)
->where('crowd_type_id', $person->crowd_type_id)
->where('id', '!=', $person->id)
->exists();
if ($alreadyLinkedInEvent) {
if ($alreadyLinked) {
return null;
}
// Guard 6: Match record already exists — return existing (idempotent)
$existing = PersonIdentityMatch::where('person_id', $person->id)
// Skip if there's already a pending or confirmed match for this person+user pair
$existingMatch = PersonIdentityMatch::where('person_id', $person->id)
->where('matched_user_id', $user->id)
->whereIn('status', [IdentityMatchStatus::PENDING, IdentityMatchStatus::CONFIRMED])
->first();
if ($existingMatch) {
return $existingMatch;
}
if ($existing !== null) {
return $existing;
// Skip if previously dismissed (don't re-suggest)
$wasDismissed = PersonIdentityMatch::where('person_id', $person->id)
->where('matched_user_id', $user->id)
->where('status', IdentityMatchStatus::DISMISSED)
->exists();
if ($wasDismissed) {
return null;
}
$match = PersonIdentityMatch::create([
'person_id' => $person->id,
'matched_user_id' => $user->id,
'matched_on' => IdentityMatchMethod::EMAIL,
'confidence' => IdentityMatchConfidence::EXACT,
'matched_on' => $method,
'confidence' => $confidence,
'status' => IdentityMatchStatus::PENDING,
'match_details' => [
'person_email' => $person->email,
'user_email' => $user->email,
'person_name' => $person->full_name,
'user_name' => $user->full_name,
'person_dob' => $person->date_of_birth?->toDateString(),
'user_dob' => $user->date_of_birth?->toDateString(),
'matched_fields' => $matchedFields,
'organisation_id' => $organisationId,
],
]);
$activityLogger = activity('identity')
->performedOn($person)
->withProperties([
'match_id' => $match->id,
'matched_user_id' => $user->id,
'matched_on' => IdentityMatchMethod::EMAIL->value,
'confidence' => IdentityMatchConfidence::EXACT->value,
'matched_on' => $method->value,
'confidence' => $confidence->value,
'matched_fields' => $matchedFields,
]);
if (auth()->user()) {
@@ -98,7 +239,6 @@ final class PersonIdentityService
public function detectMatchesForUser(User $user): int
{
// 1. Fetch all matching unlinked persons
// Person uses SoftDeletes, so trashed records are automatically excluded by Eloquent.
$normalised = strtolower(trim($user->email));
$persons = Person::whereNull('user_id')
->whereRaw('LOWER(email) = ?', [$normalised])
@@ -109,7 +249,8 @@ final class PersonIdentityService
}
// 2. Batch-check which events already have this user linked (no N+1)
$alreadyLinkedEventIds = Person::where('user_id', $user->id)
$alreadyLinkedEventIds = Person::withoutGlobalScopes()
->where('user_id', $user->id)
->whereIn('event_id', $persons->pluck('event_id'))
->pluck('event_id')
->toArray();
@@ -131,8 +272,16 @@ final class PersonIdentityService
'person_id' => $person->id,
'matched_user_id' => $user->id,
'matched_on' => IdentityMatchMethod::EMAIL,
'confidence' => IdentityMatchConfidence::EXACT,
'confidence' => IdentityMatchConfidence::HIGH,
'status' => IdentityMatchStatus::PENDING,
'match_details' => [
'person_email' => $person->email,
'user_email' => $user->email,
'person_name' => $person->full_name,
'user_name' => $user->full_name,
'matched_fields' => ['email'],
'organisation_id' => $person->event?->organisation_id,
],
]);
$activityLogger = activity('identity')
@@ -140,7 +289,7 @@ final class PersonIdentityService
->withProperties([
'matched_user_id' => $user->id,
'matched_on' => IdentityMatchMethod::EMAIL->value,
'confidence' => IdentityMatchConfidence::EXACT->value,
'confidence' => IdentityMatchConfidence::HIGH->value,
]);
if (auth()->user()) {
@@ -155,6 +304,7 @@ final class PersonIdentityService
/**
* Confirm a match: link the person to the matched user.
* Also syncs registration tags and dismisses other pending matches.
*
* @throws \DomainException if match is not pending or would violate uniqueness
*/
@@ -164,19 +314,24 @@ final class PersonIdentityService
throw new \DomainException('Match is not pending and cannot be confirmed.');
}
// Safety check: no duplicate user_id in the same event
$person = $match->person;
$conflict = Person::where('event_id', $person->event_id)
// Safety check: no duplicate user_id in the same event + crowd type
$conflict = Person::withoutGlobalScopes()
->where('event_id', $person->event_id)
->where('user_id', $match->matched_user_id)
->where('crowd_type_id', $person->crowd_type_id)
->exists();
if ($conflict) {
throw new \DomainException('User already has a person record in this event.');
throw new \DomainException('User already has a person record with this crowd type in this event.');
}
DB::transaction(function () use ($match, $person, $resolvedBy): void {
$match->update([
'status' => IdentityMatchStatus::CONFIRMED,
'confirmed_by_user_id' => $resolvedBy->id,
'confirmed_at' => now(),
'resolved_by_user_id' => $resolvedBy->id,
'resolved_at' => now(),
]);
@@ -184,8 +339,23 @@ final class PersonIdentityService
// Set user_id explicitly (not mass-assignable)
$person->user_id = $match->matched_user_id;
$person->save();
// Dismiss other pending matches for this person
PersonIdentityMatch::where('person_id', $person->id)
->where('id', '!=', $match->id)
->where('status', IdentityMatchStatus::PENDING)
->update([
'status' => IdentityMatchStatus::DISMISSED->value,
'dismissed_by_user_id' => $resolvedBy->id,
'dismissed_at' => now(),
'resolved_by_user_id' => $resolvedBy->id,
'resolved_at' => now(),
]);
});
// Sync registration tags
$this->syncRegistrationTags($person);
activity('identity')
->causedBy($resolvedBy)
->performedOn($person)
@@ -210,6 +380,8 @@ final class PersonIdentityService
$match->update([
'status' => IdentityMatchStatus::DISMISSED,
'dismissed_by_user_id' => $resolvedBy->id,
'dismissed_at' => now(),
'resolved_by_user_id' => $resolvedBy->id,
'resolved_at' => now(),
]);
@@ -220,4 +392,177 @@ final class PersonIdentityService
->withProperties(['match_id' => $match->id])
->log('person.identity.match_dismissed');
}
/**
* Revert a confirmed match — unlinks person.user_id (the "split" action).
*
* @throws \DomainException if match is not confirmed
*/
public function revertMatch(PersonIdentityMatch $match, User $revertedBy): void
{
if ($match->status !== IdentityMatchStatus::CONFIRMED) {
throw new \DomainException('Only confirmed matches can be reverted.');
}
$person = $match->person;
$previousUserId = $person->user_id;
DB::transaction(function () use ($match, $person, $revertedBy): void {
$person->user_id = null;
$person->save();
$match->update([
'status' => IdentityMatchStatus::REVERTED,
'reverted_by_user_id' => $revertedBy->id,
'reverted_at' => now(),
]);
});
activity('identity')
->causedBy($revertedBy)
->performedOn($person)
->withProperties([
'match_id' => $match->id,
'unlinked_user_id' => $previousUserId,
])
->log('person.identity.match_reverted');
}
/**
* Manually link a person to a user (organiser-initiated, no detection).
*
* @throws ValidationException if person already linked or conflict exists
*/
public function manualLink(Person $person, User $user, User $linkedBy): PersonIdentityMatch
{
if ($person->user_id !== null) {
throw ValidationException::withMessages([
'person_id' => ['Deze persoon is al gekoppeld aan een platformaccount. Ontkoppel eerst.'],
]);
}
// Check for conflict at event level (same crowd type)
$alreadyLinked = Person::withoutGlobalScopes()
->where('event_id', $person->event_id)
->where('user_id', $user->id)
->where('crowd_type_id', $person->crowd_type_id)
->where('id', '!=', $person->id)
->exists();
if ($alreadyLinked) {
throw ValidationException::withMessages([
'user_id' => ['Dit platformaccount is al gekoppeld aan een andere deelnemer met hetzelfde type bij dit evenement.'],
]);
}
$match = null;
DB::transaction(function () use ($person, $user, $linkedBy, &$match): void {
$match = PersonIdentityMatch::create([
'person_id' => $person->id,
'matched_user_id' => $user->id,
'matched_on' => IdentityMatchMethod::MANUAL,
'confidence' => IdentityMatchConfidence::HIGH,
'status' => IdentityMatchStatus::CONFIRMED,
'confirmed_by_user_id' => $linkedBy->id,
'confirmed_at' => now(),
'resolved_by_user_id' => $linkedBy->id,
'resolved_at' => now(),
'match_details' => [
'person_email' => $person->email,
'user_email' => $user->email,
'person_name' => $person->full_name,
'user_name' => $user->full_name,
'matched_fields' => ['manual'],
'organisation_id' => $person->event?->organisation_id,
],
]);
$person->user_id = $user->id;
$person->save();
// Dismiss pending matches
PersonIdentityMatch::where('person_id', $person->id)
->where('id', '!=', $match->id)
->where('status', IdentityMatchStatus::PENDING)
->update([
'status' => IdentityMatchStatus::DISMISSED->value,
'dismissed_by_user_id' => $linkedBy->id,
'dismissed_at' => now(),
'resolved_by_user_id' => $linkedBy->id,
'resolved_at' => now(),
]);
});
// Sync registration tags
$this->syncRegistrationTags($person);
activity('identity')
->causedBy($linkedBy)
->performedOn($person)
->withProperties([
'match_id' => $match->id,
'linked_user_id' => $user->id,
])
->log('person.identity.manually_linked');
return $match;
}
/**
* Unlink a person that was linked (with or without a match record).
*
* @throws ValidationException if person is not linked
*/
public function unlinkDirect(Person $person, User $unlinkedBy): Person
{
if ($person->user_id === null) {
throw ValidationException::withMessages([
'person_id' => ['Deze persoon is niet gekoppeld aan een platformaccount.'],
]);
}
// Check for confirmed match record first
$confirmedMatch = PersonIdentityMatch::where('person_id', $person->id)
->where('status', IdentityMatchStatus::CONFIRMED)
->latest()
->first();
if ($confirmedMatch) {
$this->revertMatch($confirmedMatch, $unlinkedBy);
} else {
// Direct unlink (no match record exists)
$previousUserId = $person->user_id;
$person->user_id = null;
$person->save();
activity('identity')
->causedBy($unlinkedBy)
->performedOn($person)
->withProperties(['previous_user_id' => $previousUserId])
->log('person.identity.unlinked_directly');
}
return $person->fresh();
}
/**
* Sync registration tags when identity is confirmed.
*/
private function syncRegistrationTags(Person $person): void
{
if ($person->user_id === null) {
return;
}
try {
app(TagSyncService::class)->syncFromRegistration($person);
} catch (\Exception $e) {
Log::warning('Failed to sync registration tags on identity confirm', [
'person_id' => $person->id,
'user_id' => $person->user_id,
'error' => $e->getMessage(),
]);
}
}
}