Chore/add main iamge url

[zigzagdev]

Summary

Adds main_image_url end-to-end so each World Heritage site carries the canonical image URL from the UNESCO source through the database, the read paths, the API response (thumbnail_url), and the Algolia search index.
Frontend can now display the official image for ~99% of sites without falling back to the world_heritage_site_images join. Built and merged as a sequence of small, focused sub-PRs; this PR is the rollup to main.

Motivation

• The previous list/detail responses surfaced thumbnail_url from world_heritage_site_images[0], which is gallery data and not the authoritative "main" image of a site.
• UNESCO's source JSON exposes a canonical image_url per heritage that was being dropped during normalization.
• Search results (Algolia) had no way to render the official image without re-hitting the API.

Changes

1. Schema — world_heritage_sites.main_image_url

Migration: 2026_05_04_000000_add_main_image_url_to_world_heritage_sites adds a nullable varchar(2048) column right after short_description. (PR #449)

2. Ingestion pipeline

• SplitWorldHeritageJson emits main_image_url in both the normalize and merge paths so the normalized JSON carries the value. (PR Chore/import main image url into json #450)
• ImportWorldHeritageSiteFromSplitFile persists main_image_url via the existing upsert. (PR feat: persist main_image_url via ImportWorldHeritageSiteFromSplitFile #451)
• The normalized JSON file (unesco/normalized/world_heritage_sites.json, 1.7 MB / 1248 sites) is shipped in the repo so production can run the one-shot backfill without re-running the dump+split chain. (PR chore: Backfill main_image_url #452)

3. Read paths

• WorldHeritage::$fillable includes main_image_url.
• WorldHeritageReadQueryService::findByIdsPreserveOrder and WorldHeritageQueryService::getAllHeritages include world_heritage_sites.main_image_url in their explicit SELECTs. (PR feat: surface main_image_url from WorldHeritage model and read query … #453)
• WorldHeritageDto gains an optional ?string $mainImageUrl constructor parameter and getMainImageUrl() getter.
• WorldHeritageDetailFactory::build and WorldHeritageSummaryFactory::build read main_image_url from the input array.
• WorldHeritageViewModel::getThumbnailUrl() and WorldHeritageDtoCollection::toSummaryArray() resolve thumbnail_url = main_image_url ?? images[0]?->url ?? null, preserving the legacy fallback for any site that has no main_image_url in the source.
• WorldHeritageQueryService::getHeritageById and WorldHeritageQueryService::buildWorldHeritagePayload forward main_image_url into the factory payloads so the value actually reaches the DTO. (PR Chore: Add select query into application #454, plus follow-up commits)

4. Algolia search index

AlgoliaImportWorldHeritages selects main_image_url, ships it as a top-level field on each indexed object, and switches thumbnail_url to main_image_url ?? images[0]?->url so search results match the API fallback. (PR #)

API response shape (no breaking changes)

• List endpoint (GET /api/v1/heritages): each item gains thumbnail_url (was previously thumbnail; the value now derives from main_image_url first).
• Detail endpoint (GET /api/v1/heritages/{id}): thumbnail_url returns the same fallback chain. images array still exposes the full gallery.
• Both fields are nullable: true. ~12 of 1248 sites have no source image URL (UNESCO's own data is empty for those entries) and remain null; the frontend's existing "no image" placeholder handles them.

Operational checklist (post-merge)

After this PR is merged and deployed:

1. Backfill main_image_url on existing rows (Aiven)

   The migration adds the column as NULL on all 1248 production rows. Run the documented one-shot SQL update from a host that has the deployed repo and network access to Aiven:

   python3 -c "
   import json
   with open('src/storage/app/private/unesco/normalized/world_heritage_sites.json') as f:
       rows = json.load(f)['results']
   for r in rows:
       url = r.get('main_image_url')
       if not url:
           continue
       print(f\"UPDATE world_heritage_sites SET main_image_url = '{url}' WHERE id = {r['id']};\")
   " | mysql \
       --host="$AIVEN_DB_HOST" \
       --port="$AIVEN_DB_PORT" \
       --user="$AIVEN_DB_USER" \
       --password="$AIVEN_DB_PASSWORD" \
       --ssl-mode=REQUIRED \
       "$AIVEN_DB_NAME"

Idempotent — re-running on already-populated rows is a no-op.
Expected: 1236 rows updated, 12 remain NULL (UNESCO source has no image URL for those entries).

2. Reindex Algolia (Koyeb console)

   php artisan algolia:import-world-heritages --truncate

Required so live searches surface main_image_url and the updated thumbnail_url. --truncate clears the existing index first to drop any stale objects.

3. Verify
   • GET /api/v1/heritages/1 returns "thumbnail_url": "https://whc.unesco.org/document/107413".
   • A sample Algolia search returns non-null main_image_url and thumbnail_url.

Verification (local)

• world_heritage_sites: 1248 rows / 1236 with main_image_url.
• 12 NULL ids match exactly the 12 sites where the UNESCO source JSON has empty image_url / images_urls: [140, 195, 227, 250, 335, 430, 452, 606, 783, 938, 955, 1272].
• List API surfaces thumbnail_url from main_image_url for the 1236 populated entries; the 12 stay null and the frontend's existing "no image" placeholder handles them.
• Detail API likewise resolves via the main_image_url ?? images[0] fallback.
• Algolia object objectID=1 confirmed to carry both main_image_url and thumbnail_url.
• App\Packages\Features\QueryUseCases\Tests\* — 32 tests / 278 assertions all green.

Notes / non-goals

• No new artisan command for the SQL backfill — kept as a documented one-shot per project convention for one-off ops.
• The 12 NULL entries are intentional: UNESCO's source has no image URL for them. Out of scope for this PR.
• Country resolution and the pre-existing descriptions-null bug on detail responses are unrelated and tracked separately.

[zigzagdev]

Ok