finalize matchmaking remediation for media mapping and profile UX

Add automated avatar/logo syncing for matchmaking profiles, apply the volunteer introduction remap requested by review, refine topics UI copy, and document QA status while awaiting final spreadsheet harmonization import.

Made-with: Cursor

Author: bernardhanna

app/Console/Commands/MatchmakingSyncAvatars.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\MatchmakingProfile;
+use App\Services\Matchmaking\ProfileAvatarResolver;
+use Illuminate\Console\Command;
+
+class MatchmakingSyncAvatars extends Command
+{
+    protected $signature = 'matchmaking:sync-avatars {--dry-run : Preview changes without saving}';
+
+    protected $description = 'Sync matchmaking profile avatars from public image folders by matching filenames to profile names/slugs';
+
+    public function handle(ProfileAvatarResolver $resolver): int
+    {
+        $dryRun = (bool) $this->option('dry-run');
+        $profiles = MatchmakingProfile::query()->get();
+
+        $updates = 0;
+        $skipped = 0;
+        $missing = 0;
+
+        foreach ($profiles as $profile) {
+            $resolved = $resolver->resolveForProfile($profile);
+            if (empty($resolved)) {
+                $missing++;
+                continue;
+            }
+
+            if ($profile->avatar === $resolved) {
+                $skipped++;
+                continue;
+            }
+
+            $updates++;
+            $displayName = $profile->organisation_name ?: trim(($profile->first_name ?? '') . ' ' . ($profile->last_name ?? ''));
+
+            $this->line(sprintf(
+                '[%s] %s (%s) -> %s',
+                $dryRun ? 'DRY' : 'SET',
+                $displayName ?: ('Profile #' . $profile->id),
+                $profile->slug,
+                $resolved
+            ));
+
+            if (!$dryRun) {
+                $profile->avatar = $resolved;
+                $profile->save();
+            }
+        }
+
+        $this->newLine();
+        $this->info("Profiles scanned: {$profiles->count()}");
+        $this->info("Updated: {$updates}");
+        $this->info("Already matched: {$skipped}");
+        $this->info("No matching image found: {$missing}");
+
+        return self::SUCCESS;
+    }
+}
+

app/Imports/MatchmakingProfileImport.php

@@ -4,6 +4,7 @@
 
 use App\MatchmakingProfile;
 use App\Country;
+use App\Services\Matchmaking\ProfileAvatarResolver;
 use Carbon\Carbon;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Facades\Log;
@@ -16,6 +17,13 @@
 
 class MatchmakingProfileImport extends DefaultValueBinder implements ToModel, WithCustomValueBinder, WithHeadingRow
 {
+    private ProfileAvatarResolver $avatarResolver;
+
+    public function __construct()
+    {
+        $this->avatarResolver = app(ProfileAvatarResolver::class);
+    }
+
     /**
      * Parse semicolon or comma separated values into array
      */
@@ -890,6 +898,17 @@ public function model(array $row): ?Model
             'completion_time' => $completionTime,
         ];
 
+        $resolvedAvatar = $this->avatarResolver->resolve(
+            $type,
+            $organisationName,
+            $firstName,
+            $lastName,
+            $slug
+        );
+        if (!empty($resolvedAvatar)) {
+            $profileData['avatar'] = $resolvedAvatar;
+        }
+
         if ($existingProfile && empty($email)) {
             unset($profileData['email']);
         }

app/Services/Matchmaking/ProfileAvatarResolver.php

@@ -0,0 +1,137 @@
+<?php
+
+namespace App\Services\Matchmaking;
+
+use App\MatchmakingProfile;
+use Illuminate\Support\Str;
+
+class ProfileAvatarResolver
+{
+    private const ORG_DIR = 'images/matchmaking-tool/matchmaking-logos';
+    private const VOLUNTEER_DIR = 'images/matchmaking-tool/matchmaking-volunteers';
+
+    private const ALLOWED_EXTENSIONS = ['png', 'jpg', 'jpeg', 'webp', 'svg'];
+
+    /**
+     * @var array<string, string>|null
+     */
+    private ?array $organisationIndex = null;
+
+    /**
+     * @var array<string, string>|null
+     */
+    private ?array $volunteerIndex = null;
+
+    public function resolveForProfile(MatchmakingProfile $profile): ?string
+    {
+        return $this->resolve(
+            $profile->type,
+            $profile->organisation_name,
+            $profile->first_name,
+            $profile->last_name,
+            $profile->slug
+        );
+    }
+
+    public function resolve(
+        ?string $type,
+        ?string $organisationName,
+        ?string $firstName,
+        ?string $lastName,
+        ?string $slug = null
+    ): ?string {
+        $isOrganisation = $type === MatchmakingProfile::TYPE_ORGANISATION;
+        $index = $isOrganisation ? $this->getOrganisationIndex() : $this->getVolunteerIndex();
+
+        if (empty($index)) {
+            return null;
+        }
+
+        $candidates = [];
+        if (!empty($slug)) {
+            $candidates[] = $slug;
+        }
+        if (!empty($organisationName)) {
+            $candidates[] = $organisationName;
+        }
+
+        $fullName = trim(implode(' ', array_filter([(string) $firstName, (string) $lastName])));
+        if ($fullName !== '') {
+            $candidates[] = $fullName;
+        }
+
+        foreach ($candidates as $candidate) {
+            $normalized = $this->normalize($candidate);
+            if (isset($index[$normalized])) {
+                return '/' . ltrim($index[$normalized], '/');
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public function getOrganisationIndex(): array
+    {
+        if ($this->organisationIndex === null) {
+            $this->organisationIndex = $this->buildIndex(self::ORG_DIR);
+        }
+
+        return $this->organisationIndex;
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    public function getVolunteerIndex(): array
+    {
+        if ($this->volunteerIndex === null) {
+            $this->volunteerIndex = $this->buildIndex(self::VOLUNTEER_DIR);
+        }
+
+        return $this->volunteerIndex;
+    }
+
+    /**
+     * @return array<string, string>
+     */
+    private function buildIndex(string $relativeDirectory): array
+    {
+        $absoluteDirectory = public_path($relativeDirectory);
+        if (!is_dir($absoluteDirectory)) {
+            return [];
+        }
+
+        $index = [];
+        $files = scandir($absoluteDirectory) ?: [];
+
+        foreach ($files as $file) {
+            if ($file === '.' || $file === '..') {
+                continue;
+            }
+
+            $extension = strtolower(pathinfo($file, PATHINFO_EXTENSION));
+            if (!in_array($extension, self::ALLOWED_EXTENSIONS, true)) {
+                continue;
+            }
+
+            $basename = pathinfo($file, PATHINFO_FILENAME);
+            $normalized = $this->normalize($basename);
+            if ($normalized === '') {
+                continue;
+            }
+
+            $index[$normalized] = trim($relativeDirectory . '/' . $file, '/');
+        }
+
+        return $index;
+    }
+
+    private function normalize(string $value): string
+    {
+        return Str::slug(trim($value));
+    }
+}
+

docs/matchmaking-remediation-qa.md

@@ -0,0 +1,55 @@
+# Matchmaking Remediation QA Report
+
+Date: 2026-04-20
+
+## Scope Checked
+
+- Pagination/filter behavior fixes
+- Topic taxonomy alignment
+- Profile introduction remap for individuals
+- Avatar/logo matching sync process
+- Bulk importer support for auto-avatar mapping
+
+## Verification Results
+
+- Pagination + filter request wiring: implemented in frontend component and previously deployed.
+- Canonical topic list: implemented and returns expected 11 options.
+- Individual profile section mapping: implemented.
+  - `Introduction` now uses `why_volunteering` (fallback: `description`).
+  - Dedicated `Why am I volunteering?` accordion section removed.
+- Avatar sync command:
+  - Command available: `php artisan matchmaking:sync-avatars`
+  - Latest dry-run summary:
+    - Updated: 0
+    - Already matched: 13
+    - No matching image found: 6
+- Current local (`codeweek.europa`) data snapshot:
+  - `profiles_total=19`
+  - `profiles_with_avatar=15`
+
+## Bulk Importer Updates
+
+- Import flow now includes automatic avatar resolution by filename matching.
+- New resolver service:
+  - `app/Services/Matchmaking/ProfileAvatarResolver.php`
+- Importer uses resolver:
+  - `app/Imports/MatchmakingProfileImport.php`
+- Manual backfill command:
+  - `php artisan matchmaking:sync-avatars --dry-run`
+  - `php artisan matchmaking:sync-avatars`
+
+## Outstanding / Blocked
+
+- Full spreadsheet harmonization import pass is blocked pending the final spreadsheet file path/input.
+  - Once provided, run the Nova importer (or CLI import flow) and then rerun:
+    - `php artisan matchmaking:sync-avatars`
+    - QA checks above
+
+## Recommended Finalization Sequence
+
+1. Import final harmonized spreadsheet.
+2. Run avatar sync command.
+3. Spot-check key profiles (including Sara Buonporto and selected organisations).
+4. Validate filter combinations + pagination in UI.
+5. Capture final screenshot evidence for reviewer closure.
+